c++ - コメント付きのクラス宣言を実装ファイルに含める

Question

誰もがより読みやすいコードの利点を知っています。したがって、コードを読みやすくするために、私が通常行うことは、コメント付きのクラス宣言をそのクラスの実装ファイルに含めることです。
このようにして、定義に移動するためにさまざまなインクルードディレクトリを参照する必要はありません。
それで、これは良い習慣ですか、それとも単に過剰な文書化ですか？
標準的な手法がある場合は、plzからお知らせください。
編集：
Vimでの実装からクラス宣言に移行する方法はありますか？
新しいバッファで開くことを除いて。

ありがとう

Answer 1

これは実際には逆効果です。クラス宣言を変更するときに2つではなく3つの場所を変更する必要があり、これらの場所の1つはコンパイラによってチェックされて不一致が検出されないためです。

また、大規模で急速に進化するプロジェクトでは、コメントは常に時代遅れになるため、信頼することはできません。

最新のIDEはすべて、さまざまな方法でクラス実装からクラス宣言にアクセスするのに役立ちます。これらはすべて、ファイルの先頭にスクロールしてから戻るよりも便利です。

別の方法として、 doxygenなどの自動文書化ツールの使用を検討してください。Doxygenは、クラス宣言全体をドキュメントに含めるように指示できます。構文の強調表示、行番号、ソースファイルへのリンクが含まれます。ビルドプロセスにdoxygenパスを含めることができ、常に最新のコード参照を使用できます。

Answer 2

これはDRYの原則に違反します。宣言を変更するときは、コメントを維持する必要があります。

そして、それはあなたのコードをたくさん読むのを助けません。

彼らが言うように（記憶から）：「コードとコメントが異なる物語を語っているなら、それらは確かに両方とも間違っています。」

役立つのは：

• ヘッダーのクラス宣言が十分に文書化されているか、クラスの使用法についてかなり明確であることを確認してください。これは、クラスの「手動」であるため、クラスのほとんどのユーザーが最初に見る場所です（コメントまたは明示的な関数）。 ;
• それらのコメントを、正確に何をするかではなく、あなたの意図を伝える方法で書いてください。彼らはあなたがやろうとしたことを理解できるので、あなたの実装のバグを修正します。
• ヘッダーコメントは冗長になるため、定義ファイル（cpp）で報告しないでください。
• 意図を伝える必要がある場所と、何をするのかが明確でない可能性がある場所に、定義コードにコメントを書き込みます。
• 可能であれば、実装コードのコメントを実際のコード（関数またはクラス）に置き換えます：明示的な名前の関数または明示的な名前の変数での操作の結果にコードブロックをカプセル化できることがよくあります-プログラマーはもっと突進します不明瞭なコメントよりも実行されたコード....

Answer 3

クラス定義が1画面よりも大きい場合、同僚は宣言に到達するために上にスクロールする必要があるため、これはあまり役に立ちません。最新のIDEは宣言を見つけるのに非常に優れているので、私見ではこれは役に立ちません。

時々本当に重要なのは、関数を定義するときにコメントにアクセス識別子を入れることだけです。これにより、コードを理解しようとする人の時間を大幅に節約できます。

このようなもので十分です：

//private
void Car::ReplaceDriver(const std::string & NewDriver)
{

}

Answer 4

私はそれを過剰な文書化と見なし、他の場所では見たことがありません。クラスを変更すると、コメントはすぐに同期しなくなります（または、そこを見るとわかりません）。

使用する環境はわかりませんが、宣言を探すときは、通常、エディターの関数を使用します（MacXcodeおよびWindowsVisualStudioでは、何かを右クリックして、その定義または宣言にジャンプできます）。