CまたはC ++の関数をどこに文書化するか？
複数のファイルを含むCプログラムがあるので、たとえば、いくつかの関数を実装するstuff.cと、関数プロトタイプを含むstuff.hがあります。
コメントで関数を文書化するにはどうすればよいですか？
ヘッダーファイルにすべてのドキュメント、.cファイルにすべてのドキュメントを含める必要がありますか、それとも両方のドキュメントを複製する必要がありますか？私は後者のアプローチが好きですが、一方のドキュメントを更新し、もう一方のドキュメントを更新しないという問題が発生します（通常、最初の変更を行うもの、つまり最初にヘッダーファイルを変更した場合、そのコメントそれを反映しますが、実装を更新すると、それらのコメントのみが変更されます）。
この質問とその回答はC++コードにも当てはまります—関連項目 ドキュメントのコメントはどこに置くべきですか？
関数を使用する人々が知る必要のある情報をヘッダーに入れます。
関数のメンテナが知る必要のある情報をソースコードに入れます。
doxygen のようなツールを使用する必要があるため、ドキュメントはソースコード内の特別に細工されたコメントによって生成されます。
私はGoogleC++に従うのが好きです スタイルガイド。
それは言う：
関数宣言
- すべての関数宣言の直前に、関数の機能と使用方法を説明するコメントを付ける必要があります。これらのコメントは、命令型（「ファイルを開く」）ではなく、説明的（「ファイルを開く」）にする必要があります。コメントは関数を説明しますが、関数に何をすべきかを指示しません。一般に、これらのコメントは、関数がそのタスクを実行する方法を説明していません。代わりに、それは関数定義のコメントに任せるべきです。
関数の定義
各関数定義には、関数の機能と、その機能の実行方法について注意が必要なことを説明するコメントが必要です。たとえば、定義コメントでは、使用するコーディングトリックについて説明したり、実行した手順の概要を説明したり、実行可能な代替手段を使用するのではなく、実行した方法で関数を実装することを選択した理由を説明したりできます。たとえば、関数の前半でロックを取得する必要があるのに、後半ではロックが不要な理由について説明できます。
.hファイルなど、関数宣言で指定されたコメントを繰り返すだけではいけないことに注意してください。関数が何をするかを簡単に要約することは問題ありませんが、コメントの焦点はそれがどのように機能するかにあるべきです。
私はこれを行ったり来たりして、最終的にヘッダーファイルのドキュメントに落ち着きました。 C/C++のAPIの大部分では、元のヘッダーファイルにアクセスできるため、[1]内にあるすべてのコメントにアクセスできます。ここにコメントを入れると、開発者がコメントを見る可能性が最大になります。
ただし、ヘッダーファイルとソースファイルの間でコメントが重複することは避けています（無駄のように感じます）。 Vimを使用する場合は非常に煩わしいですが、ほとんどのIDEはヘッダーファイルのコメントを取得して、インテリセンスやパラメーターヘルプなどに配置します。
[1]このルールの例外には、特定のCOMライブラリから生成されたヘッダーファイルが含まれます。
多くの場合、コーディング標準として設定されているものによって異なります。多くの人は、ドキュメントを.hファイルに入れ、実装を.cファイルに残すことを好みます。コード補完を備えた多くのIDEも、.cファイルのドキュメントよりも、これを簡単に理解できます。
しかし、ドキュメントを.hファイルに入れる際の重要なポイントは、別のプログラムと共有されるライブラリまたはアセンブリの作成に関係していると思います。配布するコンポーネントを含む.dll（または.so）を作成していると想像してください。他のプログラマーはあなたの.hを含めますが、多くの場合、その背後に実装ファイルがありません（必要もありません）。この場合、.hファイルのドキュメントは非常に貴重です。
同じプログラムで使用するクラスを作成している場合も同じことが言えます。他のプログラマーと協力している場合、ほとんどの場合、それらのプログラマーは、コードの実装方法ではなく、コードとの対話方法についてヘッダーファイルを見ているだけです。それがどのように実装されるかは、コンポーネントを使用する人やコードの問題ではありません。繰り返しになりますが、ヘッダーのドキュメントは、その人またはそれらの人がそのコードの使用方法を理解するのに役立ちます。
ヘッダーと実装のコンパイル済みバージョンのみを使用しながら、これらの関数を使用できることを考慮してください。関数を使用するために必要なものがすべてヘッダーに文書化されていることを確認してください。実装の詳細は、ソースに文書化できます。
関数宣言のないテンプレートヘッダーファイルとコメント付き関数のあるソースコードファイルを入力として受け取る簡単なスクリプトを作成しました。スクリプトは、関数定義の前の解説をソースコードファイルから抽出し、それと関連する関数宣言を出力ヘッダーファイルに書き込みます。これにより、1）関数の解説を書く必要がある場所が1つだけになります。 2）ヘッダーファイルとソースコードファイルのドキュメントは常に同期されたままです。関数の実装に関する解説は、関数の本体に入れられ、抽出されません。
あなたがそれについて考えるとき、それは本当に簡単です。
APIドキュメントは絶対にヘッダーファイルに入れる必要があります。これは外部インターフェースを定義するヘッダーファイルであるため、APIドキュメントはここにあります。
原則として、実装の詳細はAPIユーザーから隠す必要があります。これには、実装のドキュメントが含まれます（時間の複雑さなど、使用に影響を与える可能性がある場合を除く）。したがって、実装ドキュメントは実装ファイルに入れる必要があります。
ドキュメントを複数の場所で複製することは絶対にしないでください。メンテナンスが不可能になり、誰かが変更しなければならなくなるとすぐに同期がとれなくなります。
メンテナンスの悪夢を避けるために、ドキュメントを1か所に確実に保管してください。あなたは、個人的には、2つのコピーを同期させるのに十分気難しいかもしれませんが、次の人はそうしません。
doxygen のようなものを使用して、ドキュメントの「きれいな」バージョンを作成します。
ヘッダーと実装ファイルのコメントは、2つの使用方法の違いを反映している必要があります。
ヘッダーに明確に属するインターフェースドキュメント（たとえば、JavaDocsと同じ一般的な順序でDoxygenで抽出される）を作成する場合。コメントを抽出して個別のドキュメントを作成する予定がない場合でも、同じ一般的な考え方が適用されます。つまり、インターフェイス/コードの使用方法を説明するコメントは、主にまたは排他的にヘッダーに属します。
実装内のコメントは、通常、実装に関連している必要があります。頻繁な練習とは異なり、どのように物事が機能するかを説明しようとするのではなく、ほとんどの場合なぜ特定の決定が行われたのかを説明する必要があります。これは、意味のある決定を行う場合に特に当てはまりますが、それが正しいことは明らかではない場合があります（たとえば、安定したものが必要なため、クイックソートを使用しなかったことはありません。ソート）。