コメントを記入する場所はどこですか？

Question

非常に短い質問です：外部ツールでHTML文書（具体例ではDoc-o-matic）を生成できるようにするために、Delphiコードを文書化するときは、文書化コメントをインターフェイスまたは実装に入れますかセクション？

私が気に入っているのは、クラスのインターフェイス部分がクリーンでコンパクトであり、ドキュメントのコメントが実装セクションの関数間のセパレータとして機能するという点です。

一方、Doc-o-maticは、文書化のコメントを実装部分に置くと、時々問題が発生するようです。

あなたは何をお選びくださいか？

Answer 1

実装の隣にドキュメントを置くのが最善のようです。実装は、コードを変更する可能性が最も高い場所です。コードを変更するときには、ドキュメントが正しいかどうかを確認して、その2つを近くに置くこともできます。

Olaf mentionsまた、インターフェイスでの説明も含めて、ドキュメンテーションジェネレータが使用するコメントをどのように選択するか尋ねます。簡単な解決策は、単にインターフェイスでドキュメントジェネレータの特別なコメントフォーマットを使用しないことです。これらのコメントは通常の非ドキュメンテーションコメントであるとみなして無視する必要があります。したがって、実装のコメントだけがジェネレータで使用されます。または、インターフェイスに短い説明と実装の長い記述を置くことができます。ジェネレータは、コンテキストに最も適したものを使用できます（たとえば、1行記述のすべてのメソッドの一覧と単一の方法）。

SrbShell suggestsドキュメントをインターフェイスに置くと、ドキュメント作成ツールを使用しないときは、の近くにあることが確かに便利です。しかし、コード全体からドキュメンテーションを収集し、すべてをまとめたプログラムを持っている場合は、それほど重要ではありません。その場合、生成されたドキュメントもを使用してになると予想されます。ドキュメントを準備したら、コード内のドキュメントを探す必要はなく、そのドキュメントを参照してください。 IDEは、ポップアップウィンドウに説明を表示するように設定することもできるので、ほとんどの時間別の場所で見ていく必要はありません。

私は「理想的」モードと言いました。あなたの特定のツールがこれ以上理想的ではない戦略を作った場合は、それをツールに合わせて調整するか、別のツールを探します。

Answer 2

私は、可視性が高く理解しやすい実装部分にコードを記述することをお勧めします。

Answer 3

「概要」コメントをインターフェイスに、完全な説明、パラメータなどを実装部分に入れました。あなたはユニット/クラスのインターフェースを見ることができ、汚染のない状態で直ちに見ることができます。

Answer 4

インターフェイスセクションに1行のサマリーコメントを追加し、完全な詳細コメントを実装セクションに記述します。

私はDoc-O-Maticを使用しており、実装セクションのコメントでうまく動作します。実装セクションにコメントを書くときに直面している問題は何ですか？

Answer 5

オブジェクトの前にインターフェイスにドキュメントを配置して、設計上の問題、設計ドキュメントへのリンク、またはオブジェクトクラスのユーザーが知っておく必要のある事項を説明することをお勧めします。メソッドの場合、宣言の直後、開始の前に、実装セクションで個別に個別に文書化します。各ユニットのヘッダーには、ユニット名の直後にリリースノート/履歴セクションを含めることができます。

は一般的に、私のメソッドのコメントブロックは、（テンプレートを経由して）次のようになります。

{==============================================================================} 
Procedure Form1.DoSomething; 
{$region 'xmldoc'} 
///<summary></summary> 
///<author>skamradt</author> 
///<param name=''></param> 
///<returns></returns> 
///<exception cref=""></exception> 
///<since>2009-05-22</since> 
{$endregion} 
{------------------------------------------------------------------------------} 
begin 
    // code goes here. 
end;