web-dev-qa-db-ja.com

ドキュメントのコメントはどこに置くべきですか？

このように、前方宣言を含むヘッダーファイル、または実装を含む.cppファイルで？

//header.h
/* About foo() */
void foo();
/* About bar() */
int bar();
/* About A */
class A
{
public:
    /* About A's constructor */
    A();
    ....
}

または

//implementation.cpp
/* About foo() */
void foo()
{
    ...
    ...
}
/* About bar */
int bar()
{
    ...
}
/* About A's constructor */
A::A()
{
    ...
}
c++headerdocumentation
32
wrongusername

使用法については、ヘッダーに入れるとよいでしょう。それは人々が最初に見る場所です。

コンポーネントの使用方法を理解するために.cppファイルを調べる必要がない場合、ドキュメントは本当に成功します。

41
Johan Kotlinski

私の知る限り、.hファイルで何かを変更するたびに、そのヘッダーファイルを含むすべてのファイルが再コンパイルされます。このため、コメントのほとんどを.cppファイルに入れています。

6
Ray Zhou

C++の場合、cppとhの両方に「ドキュメントコメント」を入れます。

Cppにはコードが含まれており、それらを説明するすべての主要なコード要素（クラス、メソッドなど）に関するドキュメントコメントがあります-通常はdoxygenまたはDocumentation XMLコメント形式です（外部ドキュメントを生成する傾向はありませんが、便利だと思います） canが必要だと判断した場合に、外部ツールに抽出できる標準化された形式に固執すること。これは、呼び出し元がメソッドを使用する方法を正確に説明する包括的なドキュメントであり、コードを変更しようとする人が理解する必要のある設計の詳細も説明しているため、呼び出し元は意図、「契約」、および理解すべき重要事項を理解できます。コードの操作について。 （Visual Studio用のアドイン AtomineerUtils を作成しました。これにより、これらのコメントの作成と更新がすばやく簡単になります。したがって、このようなことを一貫して包括的に文書化するのはそれほど手間がかかりません）

私のヘッダーは要約として扱われます（コンパイラーと私自身の両方）-各メソッドを簡単に説明する1行の//コメントを使用します。これにより、（できれば比較的自己文書化された）メソッド/パラメーター名よりも多くの情報が得られますが、cppの詳細な文書よりもはるかに少なくなります。これは、ほとんどの場合メソッドを使用するのに十分な詳細を取得するために実際の実装を確認する手間を省く要約またはリマインダーと考えてください。

5
Jason Williams

コメントは、ファイルの宣言、つまり、拡張子が.hで終わるヘッダーファイルまたはインターフェイスファイルに配置する必要があります。

おそらく、配布の場合、ヘッダーファイルと.cppファイルをバイナリ形式で出荷する予定です。つまり、読み取り可能ではないため、誰かがコメントを読むことを期待する場合は、ヘッダーファイル内にある必要があります。

.cppファイルに自然に配置されているだけの実装ドキュメントもあります。

いずれにせよ、ドキュメントツールを使用して、非常に一般的に使用されている2つまたは3つのJavadocの便利なタグを学習することをお勧めします。冒頭のコメントを///または/ **に変更する必要があります

//header.h
/** @brief About power()
    @see lpower
    @param x The base to power
    @param y The exponent, number of times to multiply base by itself
    @return x^y
*/
int power(int x, int y);
3
Baltasarq

ある種の自動ドキュメントジェネレータを使用している場合、コメントは、コメントが必要であると指示された場所に配置する必要があります。

それ以外の場合は、関数declarationではなく関数definitionの横に一般的な"this function does X"コメントを配置します（もちろん、関数はその定義で宣言されます）。

関数宣言は少しかさばる可能性があるため、ヘッダーファイルにドキュメントを配置すると、通常、特定のクラスに関連するすべてのコメントを一度に表示するのがはるかに簡単になり、他の開発者がそのクラスを一目で理解できるようになります。

3
ClosureCowboy

Doxygenを使用すると、どちらからもドキュメントが生成されますが、ヘッダーと実装の両方にドキュメントが表示される場合は、ヘッダーが優先されるため、重複を避けてヘッダーをドキュメント化します。

また、ヘッダーは、クラスのユーザーが関心を持っているユーザーインターフェイスを定義します。さらに、コードをライブラリまたはオブジェクトコードとしてデプロイした場合、ヘッダーはユーザーがアクセスできる唯一のソースです。

2
Clifford