プログラマはコードの背後にある拡張ロジックをどこで説明すべきですか？
C＃でいくつかの定量ライブラリを開発しました。XMLDocコメントに関連する古典的な情報（メソッドシグネチャの基本情報を含む）だけでなく、メソッド内で使用されている数式も理解することが重要です。
したがって、コードに拡張ドキュメントを含めることができるようにしたいと考えています。これには、たとえば、ラテックスの数式、グラフなどを含めることができます。
そのような情報をAPIドキュメントに含める必要があると思いますか？
または、例として開発ブログに含める必要がありますか？
この種の目的で通常使用される一般的なツールはありますか？
私に関する限り、ドキュメントをコードに近づけるほど、コードが最新の状態に保たれ、有用性が高まります。
そのため、ユーザーマニュアルも含めて、すべてのドキュメントをコードと同じリポジトリに保管し、リビジョン管理システムで簡単に管理できるプレーンテキスト形式で保管しようとしています。
コード内ドキュメント
これはすでにカバーされているようですが、実際に選択した開発環境でドキュメント機能を使用していることを覚えておくことが重要です（ pydoc for python、 javadoc in Javaまたは xmlコメント （C＃の場合）は、最も重要なドキュメント手法の1つです。これにより、コードの記述と同時にドキュメントを簡単に記述できます。
後で戻って物事を文書化することに依存している場合、それを回避することはできませんが、コードを記述しているときにそうする場合、文書化する必要があることは心に新鮮です。 C＃には、XMLドキュメントが不完全であるか、実際のコードと一致しない場合にコンパイル警告を発行するオプションもあります。
ドキュメントとしてのテスト
もう1つの重要な側面は、適切な統合と単体テストを行うことです。
多くの場合、ドキュメントは、クラスとメソッドが単独で何を行うかに焦点を当て、それらを一緒に使用して問題を解決する方法をスキップします。多くの場合、テストでは、相互のやり取りを示すことにより、これらをコンテキストに組み込みます。
同様に、単体テストでは、外部依存関係を明示的に指摘することがよくあります。これにより、 Mock を実行する必要があります。
テスト駆動開発 を使用していることにも気づきました。Wordから直接使用しているため、使いやすいソフトウェアを作成しています。優れたテストフレームワークを使用すると、コードをテストしやすくすることと使いやすくすることは、ほとんど同じです。
より高いレベルのドキュメント
最後に、システムレベル、アーキテクチャ、開発者、そして場合によってはエンドユーザーのドキュメントについても何をすべきかがあります。多くの人がwikiやWordやその他のワードプロセッサを使用してそのようなドキュメントを書くことを提唱しますが、私にとって、そのようなドキュメントの最適な場所は、バージョン管理システムにやさしいプレーンテキスト形式でコードと並んでいることです。
コード内ドキュメントと同様に、上位レベルのドキュメントをコードリポジトリに保存すると、ドキュメントを最新の状態に保つことができます。また、コードのバージョンX.Yを引き出すときに、ドキュメントのバージョンX.Yも得られるという利点があります。さらに、VCSに適した形式を使用する場合は、コードと同じように、分岐、差分、マージを簡単に行うことができます。
Htmlページとpdfドキュメントの両方を簡単に作成でき、 LaTeX よりも使いやすいので、- rst は非常に気に入っていますが、 LaTeX数式 あなたがそれらを必要とするとき。
非常に数学的なコードを書くとき、プロジェクトリポジトリにいくつかの wxmaxima ドキュメントがあると便利です。プレーンテキストであるため、これらも適切に分岐、比較、マージされますが、 コンピュータ代数システム を使用すると、式の一貫性チェックとドキュメント化に役立ちます。
そのようなドキュメントをXMLコメント内に含め、LaTeXマニュアル、Webページ、その他のドキュメントを doxygen を使用して生成できます。使用 <remarks>および<example>拡張散文の要素。
ライブラリがどのように機能するかを説明するためにクラス図、グラフ、数式、画像などを含める必要がある場合は、外部のドキュメントを使用します。この外部ドキュメントをライブラリリリースの一部として、適切と思われる形式（LaTeXまたはその他）で含めます。必要に応じて、コードからこのドキュメントを参照できます（たとえば、「詳細については、「Readme」ドキュメントを参照してください」）。
重要なのは、一貫性だと思います。メソッドに一貫して注釈を付けている場合は、たとえば、 Doxygenは、拡張ロジックの説明をそこに含めることだけが理にかなっています。これは、他の開発者が見そうな場所だからです。突然開発者を他のドキュメントに向けることは不必要に思え、開発者を混乱させるだけです。
ただし、プログラム全体の説明が別の場所に示されている場合は、それをそのまま使用して、そこに拡張ロジックの説明を与える必要があります。
APIのメソッドの内部を文書化する必要があると思われる場合は、インターフェイスを十分に定義またはモジュール化していない可能性があります。
よく書かれたAPIは、内部構造がどのように機能するかを理解するためにプログラマーに要求するべきではありません。また、その動作方法を不必要に文書化することにより、抽象化レイヤーを壊し、特定の実装に固執することになりますが、これも適切ではありません。