機能的なプログラミングドキュメント[閉じた
-
22-09-2019 - |
質問
機能的言語の標準的なドキュメント(OOのUMLのような)はありますか? Erlangで書かれたCouch DBをダウンロードし、ソースコードを見てショックを受けた後、ドキュメントのラインはほとんどありません。これらすべての機能が互いにどのように依存しているかを文書化する必要はありませんか?より良い文書化された中型プロジェクトも自由に利用可能になりましたか?
解決
言語に関係なく、コードを文書化する必要があります。
あるようです Edocと呼ばれる標準的なドキュメントスタイル. 。 EDOCは、外部APIドキュメントを作成できます。 1つのソースからの引用:
EDOCは、Erlangコード内にErlang APIを直接文書化するためのErlang標準アプリケーションです。
これはで参照されます erlang.orgのドキュメントセクション:
EDOCでは、「@Name ...」というフォームにタグを使用して、ソースコード自体のコメントとしてErlangプログラムのドキュメントを書くことができます。ソースファイルは、ドキュメントを生成するためにEDOCのタグを含める必要はありませんが、タグがない場合は、モジュールから抽出できる基本的な利用可能な情報のみが含まれます。
a 焦点を合わせたGoogle検索 ここからあなたを連れて行きます。
他のヒント
HaskellやMLなどの機能的言語では、タイプとモジュールタイプ(標準MLの「署名」と呼ばれる)を備えたもので、このタイプは非常に多くのドキュメントを提供します。コンパイラによってチェックされていないタイプのスキームのような機能的言語では、代わりに「契約」を使用します。
ErlangはEricssonで開発され、テレコムズ業界には非常に強力な文化とテストの記録があります。これらの機能がどのように機能するかという文書がどこかのテストスイートにあるかの文書があっても、私を驚かせることはありません。
概要: 標準に最も近い2つのものは、タイプ(静的タイプシステムを持つ機能言語の場合)と契約(静的タイプシステムを持たない機能的言語用)です。
これは非常に興味深い問題です!
2つの問題があります。最初の問題は、コードにコメントし、いくつかのドキュメントを作成することです(テキスト形式)。これは、OO言語のように通常の方法で行う必要があります。プロジェクトで使用するすべてのモジュール、関数、およびタイプの概要を作成するだけです。 F#(.NETの関数言語)では、F#と同じようにXMLコメントをかなり似た方法で記述し、これらのコメントからドキュメントを生成できます。私は信じています F#ドキュメント MSDNは、これらのコメントから自動的に生成されます。 F#ソースコードの例を次に示します(VS 2008のF#をインストールすると、コアライブラリのソースコードもインストールします。これは興味深いリソースである可能性があります):
/// Return the first element of the list.
///
/// Raises <c>System.ArgumentException</c> if <c>list</c> is empty
val head: list:'T list -> 'T
あなたが言及した2番目のことはUMLです - 機能的言語の図を描く標準はありません。これは難しい問題のようです。ただし、特定のライブラリを使用するコードの図を作成することは確かに可能です。多くの機能ライブラリを使用すると、いくつかの単純な関数を作成してコードを作成できます。リスト処理は良い例です。
let custNames = customers |> List.map (fun customer -> customer.Name)
let empNames = employees |> List.map (fun employee -> employee.Name)
let result = List.concat [custNames; empNames]
これは、データフローを描画することで視覚的に表現できます。
+-----------+ +-----+
| customers |--->| map |\
+-----------+ +-----+ \ +--------+ +--------+
>| concat |-->| result |
+-----------+ +-----+ / +--------+ +--------+
| employees |--->| map |/
+-----------+ +-----+
多くの機能ライブラリで同様の図面を実行でき、それらは非常に便利であるように見えます(これは、ホワイトボードで何かを議論するときに描くものです)。ただし、私が知る限り、これを自動的に行うツールはありません(ただし、iMhoは可能ですが)。