科学ソフトウェアを文書化する良い方法は何ですか？

多くの場合、他の人が書いた科学的コード（または、時には自分の研究でさえ）を継承または遭遇したときに、ドキュメントがまばらであるか存在しないことに気付きました。運が良ければ、有益なコメントが表示されます。運が良ければ、DoxygenのコメントとDoxyfileさえありますので、関数インターフェースといくつかのフォーマットされたHTMLを参照してください。私が非常に幸運なら、Doxygenとソースファイルのコメントに加えてPDFマニュアルと例があります。そして、私は非常に楽しかったです。

ソースコードの文書化に役立つ情報とツールは何ですか？さらに言えば、科学ソフトウェアの場合、そのソースコードに付随するデータと結果を文書化するのにどのような情報とツールが役立ちますか？

科学ソフトウェアのドキュメントは3つのカテゴリに分類でき、それらはすべて完全に理解するために必要です。最も簡単で最も一般的なのは、個々のメソッドのドキュメントです。これには多くのシステムがあります。あなたはdoxygenに言及し、Pythonにはpydocがあり、PETScには以下を生成する独自のパッケージ播種があります。

ただし、単純なユーティリティを超えるソフトウェアについては、マニュアルが必要です。これにより、パッケージの目的の概要と、この目的を達成するためにさまざまな機能がどのように統合されるかがわかります。多くの場合、例を使用することで、新しいユーザーがコードを構造化するのに役立ちます。PETScでは、マニュアルにLaTeXを使用していますが、PyClawパッケージではSphinxフレームワークを使用しています。播種パッケージに実装した非常に便利なものの1つは、サンプルコードと関数ドキュメント間のリンクです。たとえば、この例Bratu方程式を解きます。カスタムタイプまたは関数呼び出しのリンクをたどって低レベルのドキュメントにアクセスする方法、およびそれらのページがそれらを使用して例にリンクする方法に注意してください。これは、プロジェクトの他の人々が貢献する新しい機能について学ぶ方法です。

よく見落とされているドキュメントの一部は、開発者向けドキュメントだと思います。コーディングスタイルのドキュメントとリポジトリと対話するための指示を公開することは珍しくありません。ただし、実装前に行われた設計上の決定を説明することは非常にまれです。これらの決定には常にトレードオフが伴い、ハードウェアとアルゴリズムに関する状況は時間とともに必然的に変化します。特定の設計決定について検討したトレードオフと理論的根拠についての議論がなければ、後のプログラマーはプロセス全体を自分で再作成する必要があります。これは、元の開発者がもはや担当していない場合に、古いコードのメンテナンスと改善を成功させるための大きな障害だと思います。

コード内ドキュメント

最も重要なことは、選択した開発環境でドキュメント機能を使用することです。つまり、Pythonのpydoc、javaのjavadocまたはC＃のxmlコメントを意味します。これらにより、コードの記述と同時にドキュメントの記述が簡単になります。

戻ってきて後で物事を文書化することに依存している場合、それを回避することはできませんが、コードを書いているときにそれを行うと、文書化する必要があるものが頭に浮かぶでしょう。C＃には、XMLドキュメントが不完全または実際のコードと一致しない場合にコンパイル警告を発行するオプションもあります。

ドキュメントとしてのテスト

もう1つの重要な側面は、適切な統合と単体テストを行うことです。

多くの場合、ドキュメントはクラスとメソッドが単独で行うことに集中し、それらを一緒に使用して問題を解決する方法をスキップします。テストでは、これらが相互にどのように相互作用するかを示すことで、これらをコンテキストに入れます。

同様に、単体テストでは、モックアウトが必要な外部依存関係を明示的に指摘することがよくあります。

また、テスト駆動開発を使用すると、使いやすいソフトウェアを作成することがわかります。優れたテストフレームワークでは、コードをテストしやすくすることと使いやすくすることは、多くの場合同じことです。

高レベルのドキュメント

最後に、システムレベルとアーキテクチャのドキュメントについて何をすべきかがあります。多くの人は、このようなドキュメントをwikiで書くか、Wordまたは他のワードプロセッサを使用することを推奨しますが、私にとっては、このようなドキュメントの最適な場所は、コードと共に、バージョン管理システムに優しいプレーンテキスト形式です。

コード内のドキュメントと同様に、コードリポジトリに高レベルのドキュメントを保存すると、常に最新の状態に保つことができます。また、コードのバージョンXYを取り出すと、ドキュメントのバージョンXYも取得できるという利点があります。さらに、VCSフレンドリ形式を使用する場合、コードと同様に、ドキュメントを簡単に分岐、差分、およびマージできます。

私はかなりのようなreStructuredTextの（RST） 、使用してそれからHTMLページとPDF文書の両方を生成することが容易であるスフィンクスを、そしてよりはるかに友好的である乳液、それでも含むことができ、LaTeXの数式表現をあなたがそれらを必要とするとき。

私は、ファヒームが作るほとんどすべての点で異議を唱えます。具体的には：

1 /「科学開発者がソフトウェアの文書化に多くの時間を費やすことを期待するのは非現実的だと思う」これは失敗したプロジェクトの処方箋であり、すぐに主要開発者にアクセスできない人は誰も使用できなくなります。大きな科学計算ライブラリ（PETSc、deal.IIなど）には、数千ページ以上に及ぶ膨大なドキュメントがあるのは十分な理由です。豊富なドキュメントがない場合、かなりのユーザーコミュニティを持つことはできません。ただし、サンプルコードはシンプルで、単一の概念に焦点を当てる必要があることに同意します。

2 /「著者は、適切な場合、出版のために論文を書くことを検討すべきです」。それは実際にはしばしば不可能です。コンセプトやアルゴリズムに関する論文を書くことはできますが、インターフェースやその他の設計上の決定については書くことはできません。そのような論文の読者は、実装が何をするのかを知るでしょう。実装のユーザーは、呼び出す関数、引数の意味などを知る必要があります。ユーザーとして、ほとんどの場合、前者なしで生きて、単にライブラリをブラックボックスと見なすことができますが、インターフェース情報。

これはいい質問です。最初の概算では、コードは自己文書化を試みる必要があります。ソフトウェアは、コマンドラインであれば、たとえば、あなたが行うことができる必要がありますexecutable --helpかexecutable -h、あるいはexecutable（実行ファイルが引数なしで何もしない場合）、および簡単な使用法のメッセージ・リターンを持っています。

第二に、科学的な開発者がソフトウェアの文書化に多大な時間を費やすことを期待するのは非現実的であると思うので、単純にすることをお勧めします。基本的な方法とオプション、注釈付きの作業およびテスト済みの短いテキストマニュアル単純なものから複雑なものへと段階的に変化する使用例（使用例は非常に重要であり、しばしば無視されます）は、ほとんどの科学ソフトウェアが提供するものよりもはるかに優れています。また、使用例についての嫌悪感を追加したいと思います。シンプルはシンプルを意味します。つまり、メソッドを説明しようとする場合、読者を混乱させるために10の無関係な概念やメソッドを追加しないでください。簡潔に保ち、注釈を付けて、読者が例の実行内容を把握できるようにします。また、手動の使用例をテストスイートに結び付けて、コードが変更されても機能するようにすることをお勧めします。実際にこれをうまくやる方法がわからないので、気軽に教えてください。開発者がもっと凝りたい場合は、素敵なマークアップ言語などを使用したり、manページを追加したりできることを確認してください。

第三に、著者は、必要に応じて出版用の論文を書くことを検討すべきです。これは通常、設計上の決定に対処し、マニュアルよりもソフトウェアに関するより高いレベルの視点を提供します。これは、@ Mattが話していた設計決定の文書化に対処します。

もちろん、すべての最も重要なドキュメントはコード自体であり、必要に応じてコメントする必要があります。これは、コードがフリーソフトウェアであることを前提としています。そうでない場合、科学ソフトウェアとしては実質的にあまり有用ではありません（メソッドの実装方法がわからないブラックボックスを本当に使用したいですか？）、私はそれを使用しません。

データと結果を文書化する方法に関する質問に対処するために、Pythonのdoctest moduleのようなものをお勧めします。これにより、自動的に検証できる方法でチュートリアルまたはテストを作成できます。

文芸的プログラミングに興味があるなら、org-babelを見てください。Emacsのorg-modeの一部であるため、ドキュメント用の幅広いエクスポートオプション（LaTeX、PDF、HTML、ODT）が提供されます。Emacsはバッファー内に画像を表示し、LaTeX構文で数式を記述できるため、プレーンテキストのドキュメントに制限する必要がありません。

ソースコードから自動的に生成されるドキュメントは、最新の、つまり正しいドキュメントを作成するために不可欠なコンポーネントです。開発者がドキュメントに無関心であるために、ソースコードよりも何年も遅れているドキュメントを見た回数は数えられません。簡単な解決策は、プログラマーが新しいコードとともにドキュメントを同じ場所で同時に書くことを簡単にすることです。より輝かしい活動のために必然的に優先順位を下げることは避けられません。

選択を余儀なくされた場合、詳細で正確な（つまり、現在の）ソースコードコメントが欲しいのですが、間違った情報でいっぱいの古いユーザーマニュアルよりもユーザーマニュアルはありません。

Pythonにはpep8とpep257というツールがあり、ドキュメントの欠落や不正な形式を報告します。Emacsのelpyは、ドキュメントの欠落についても文句を言います。reStructuredTextを使用したNumpyのdocstringの規則に従うことをお勧めします。pep8、pep257、doctestを使用したテストは、py.testとtoxを自動的に実行してセットアップできます。