109

常識的には、Doxygen コメント ブロックは、クラス、構造体、列挙型、関数、宣言があるヘッダー ファイルに配置する必要があります。これは、ソースなしで配布されることを意図したライブラリ (オブジェクト コードを含むヘッダーとライブラリのみ) の妥当な議論であることに同意します。

しかし...私は、完全なソースコードで使用される社内の (または自分自身のサイドプロジェクトとして) ライブラリを開発しているときに、正反対のアプローチを考えていました。私が提案するのは、実装ファイル (HPP、INL、CPP など) に大きなコメント ブロックを配置して、ヘッダーで宣言されたクラスと関数のインターフェイスが乱雑にならないようにすることです。

長所：

  • ヘッダー ファイルの混乱が少なくなり、関数の分類のみを追加できます。
  • たとえば、Intellisense の使用時にプレビューされるコメント ブロックは衝突しません。これは、.H ファイルに関数のコメント ブロックがあり、同じ .H ファイルにそのインライン定義がある場合に見られる欠陥です。ただし、.INL ファイルから含まれています。

短所：

  • (明らかなもの) コメント ブロックは、宣言があるヘッダー ファイルにはありません。

それで、あなたは何を考え、おそらく提案しますか？

4

8 に答える 8

86

人々がコードを使用したり作業したりするときに読み書きできる場所にドキュメントを置きます。

クラスのコメントはクラスの前に置き、メソッドのコメントはメソッドの前に置きます。

これは、物事が維持されていることを確認するための最良の方法です。また、ヘッダー ファイルを比較的無駄のない状態に保ち、メソッド ドキュメントを更新することでヘッダーがダーティになり、再構築がトリガーされるという、人に触れる問題を回避します。後でドキュメントを書くための口実として人々がそれを使用することを実際に知っています!

于 2009-01-14T23:18:26.267 に答える
85

名前は複数の場所で文書化できるという事実を利用するのが好きです。

ヘッダーファイルに、メソッドの簡単な説明を記述し、そのすべてのパラメーターを文書化します。これらは、メソッド自体の実装よりも変更される可能性が低く、変更される場合は、関数プロトタイプを変更する必要があります。 。

実際の実装の横にあるソースファイルに長い形式のドキュメントを配置しているので、メソッドが進化するにつれて詳細を変更できます。

例えば：

mymodule.h

/// @brief This method adds two integers.
/// @param a First integer to add.
/// @param b Second integer to add.
/// @return The sum of both parameters.
int add(int a, int b);

mymodule.cpp

/// This method uses a little-known variant of integer addition known as
/// Sophocles' Scissors. It optimises the function's performance on many
/// platforms that we may or may not choose to target in the future.
/// @TODO make sure I implemented the algorithm correctly with some unit tests.
int add(int a, int b) {
  return b + a;
}
于 2011-10-12T08:23:41.683 に答える
20

ヘッダーにコメントがあるということは、コメントが変更された場合、クラスのすべてのユーザーを再コンパイルする必要があることを意味します。大規模なプロジェクトの場合、次の 20 分間をすべての再構築に費やすリスクがある場合、コーダーはヘッダーのコメントを更新する傾向が少なくなります。

そして.. ドキュメントのコードをブラウズするのではなく、html ドキュメントを読むことになっているので、ソース ファイル内でコメント ブロックを見つけるのがより困難であることは大きな問題ではありません。

于 2009-01-09T14:22:33.233 に答える
14

ヘッダー: ファイルを表示するときに他の「ノイズ」が少ないため、コメントが読みやすくなります。

ソース: 次に、コメントを見ながら実際の関数を読み取ることができます。

ヘッダーでコメントされているすべてのグローバル関数と、ソースでコメントされているローカル関数を使用するだけです。必要に応じて、 copydoc コマンドを含めて、ドキュメントを複数の場所に挿入することもできます (メンテナンスに適しています)。

ただし、簡単なコマンドを使用して、結果を別のファイル ドキュメントにコピーすることもできます。例:-

私のファイル1.h

/**
 * \brief Short about function
 *
 * More about function
 */
WORD my_fync1(BYTE*);

私のファイル1.c

/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}

これで、両方の機能について同じドキュメントを取得できます。

これにより、コード ファイルのノイズが少なくなると同時に、1 か所に記述されたドキュメントが最終出力の複数の場所に表示されます。

于 2008-12-10T10:39:46.947 に答える
2

プログラミングにQtCreatorを使用しています。非常に便利なトリックは、Ctrlキーを押しながら関数またはメソッドをクリックして、ヘッダーファイルの宣言を取得することです。

メソッドがヘッダーファイルでコメント化されている場合、探している情報をすばやく見つけることができます。したがって、私にとって、コメントはヘッダーファイルに配置する必要があります。

于 2012-09-24T20:34:15.593 に答える
2

通常、インターフェイスのドキュメント (\param, \return) を .h ファイルに、実装のドキュメント (\details) を .c/.cpp/.m ファイルに入れます。Doxygen は、関数/メソッドのドキュメントのすべてをグループ化します。

于 2009-01-05T15:06:51.547 に答える
2

すべてをヘッダーファイルに入れます。

私はすべてを文書化しますが、通常はパブリック インターフェイスのみを抽出します。

于 2009-01-08T10:29:14.537 に答える
-1

C++ では、ヘッダー モジュールと .cpp モジュールの間で実装を分割できる場合があります。ここでは、すべてのパブリック関数とメソッドが保証されている唯一の場所であるため、ドキュメントをヘッダー ファイルに入れる方がきれいに見えます。

于 2013-11-15T20:06:15.297 に答える