プログラマはコードの背後にある拡張ロジックをどこで説明すべきですか？

私はC＃でいくつかの定量ライブラリを開発しました。XMLDocコメントに関連する古典的な情報（メソッドシグネチャの基本情報を含む）だけでなく、メソッド内で使用されている数式も理解することが重要です。

したがって、コードに拡張ドキュメントを含めることができるようにしたいと考えています。これには、たとえば、ラテックスの数式、グラフなどを含めることができます。

そのような情報をAPIドキュメントに含める必要があると思いますか？

または、例として開発ブログに含める必要がありますか？

この種の目的で通常使用される一般的なツールはありますか？

私に関する限り、ドキュメントをコードに近づけるほど、コードは最新の状態に保たれ、有用性が高まります。

そのため、ユーザーマニュアルも含めて、すべてのドキュメントをコードと同じリポジトリに保管し、リビジョン管理システムで簡単に管理できるプレーンテキスト形式で保管しようとしています。

コード内ドキュメント

これはすでにカバーされているようですが、選択した開発環境でドキュメント機能を実際に使用すること（Pythonの場合はpydoc、javaの場合はjavadoc、C＃の場合はxmlコメント）が最も重要なドキュメント手法であることを覚えておくことが重要です。それらはコードを書くと同時にドキュメンテーションを書くことを容易にします。

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

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

別の重要な側面は、優れた統合と単体テストを持っていることです。

多くの場合、ドキュメントは、クラスとメソッドが単独で何を行うかに焦点を当て、それらを一緒に使用して問題を解決する方法をスキップします。多くの場合、テストでは、相互のやり取りを示すことにより、これらをコンテキストに組み込みます。

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

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

より高いレベルのドキュメント

最後に、システムレベル、アーキテクチャ、開発者、そして場合によってはエンドユーザーのドキュメントについても何をすべきかがあります。多くの人がwikiやWordやその他のワードプロセッサを使用してそのようなドキュメントを書くことを提唱しますが、私にとっては、そのようなドキュメントの最適な場所は、バージョン管理システムにやさしいプレーンテキスト形式のコードと並んでもいます。

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

htmlページとpdfドキュメントの両方を簡単に作成でき、LaTeXよりも使いやすく、しかもLaTeX数式を含めることができるため、私はrstが非常に好きです。必要ときです。

非常に数学的なコードを書くとき、プロジェクトリポジトリにいくつかのwxmaximaドキュメントがあると便利です。プレーンテキストであるため、これらも適切に分岐、比較、マージされますが、コンピューター代数システムを使用すると、数式の整合性チェックとドキュメント化に役立ちます。

XMLコメント内にそのようなドキュメントを含め、doxygenを使用して、そこからLaTeXマニュアル、Webページ、およびその他のドキュメントを生成できます。使用<remarks>して<example>拡張された散文のための要素を。

ライブラリがどのように機能するかを説明するためにクラス図、グラフ、数式、画像などを含める必要がある場合は、外部のドキュメントを使用します。この外部ドキュメントをライブラリリリースの一部として、適切と思われる形式（LaTeXまたはその他）で含めます。必要に応じて、コードからこのドキュメントを参照できます（たとえば、「詳細については、「Readme」ドキュメントを参照してください」）。

重要なのは、一貫性ですです。Doxygenなどで抽出できるコメントでメソッドに一貫して注釈を付けている場合は、そこに拡張ロジックの説明を含めることだけが意味があります。これは、他の開発者が見そうな場所だからです。突然他のドキュメントを開発者に向けることは不必要に思え、開発者を混乱させるだけです。

ただし、プログラム全体の説明が別の場所に記載されている場合は、それをそのまま使用し、そこに拡張ロジックの説明を記載する必要があります。

APIのメソッドの内部を文書化する必要があると思われる場合は、インターフェイスを十分に定義またはモジュール化していない可能性があります。

よく書かれたAPIは、内部構造がどのように機能するかを理解するためにプログラマーに要求するべきではありません。また、その動作方法を不必要に文書化することで、抽象化レイヤーを壊し、特定の実装に固執することになりますが、これも適切ではありません。