コメントを書くための初心者向けガイド？

開発者の発芽を目的とした、コードコメントの作成に関する決定的なガイドはありますか？

理想的には、コメントをいつ使用するべきか（使用すべきではない）、およびコメントに何を含めるべきかについて説明します。

この答え：

何をしているのかをコメントしないでください。

WHATは、それをサポートする変数名を適切に選択した、クリーンで読みやすいシンプルなコードによって処理されます。コメントは、コード自体では表示できない（または表示が難しい）コードの上位レベルの構造を示します。

近づきますが、経験の浅いプログラマーにとっては少し簡潔です（いくつかの例とコーナーケースでの拡張は素晴らしいと思います）。

更新：ここでの回答に加えて、別の質問に対するこの回答は非常に関連性が高いと思います。

コメントの最大の弱点に注意する必要があります。コメントは古くなっています。つまり、コードの変更に伴い、開発者がコメントを更新してコードとの同期を保つことはめったにありません。これは、あなたがそれらを決して信用できず、それでもコードを読むことになってしまうことを意味します。このため、コードは自己文書化する必要があります。コードが散文のようになるように、関数名と変数名を選択する必要があります。

そのため、コードが実行していることを文書化しないでください。自己文書化コードがそれを処理する必要があります。あなたがそれをしている理由を文書化してください。WHYは通常、ビジネスルール関連またはアーキテクチャ関連であり、頻繁に変更されることはなく、WHATですぐに失効します。ドキュメントエッジケース。例外を文書化します。設計の決定を文書化します。そして最も重要なことは、あなたが考慮したが、実装しないことに決めた設計上の決定を文書化します（そして、それらを使用しないことに決めた理由を文書化します）。

Robert C. MartinのClean Code bookを読んでください。コメントが必要な場合は、適切にコーディングしていない可能性が高いと説明されています。理想的には、コードは「自己コメント」である必要があります。Clean Coderの本は、これを行う方法を説明しているため、コメントは不要であり、必要な状況でコメントを行う方法については十分に説明しています。（複雑な数式を説明するなど）

前述のように、Code Completeにはコメントの作成に関するさまざまなガイドラインがあります。つまり、PDLであり、次のように要約できます。

1. コードが何をしているかではなく、あなたの意図を説明してください。何らかのトリックを使用している場合、またはカスタム実装を使用している場合を除き、実装の詳細を説明しないでください。たとえば、シフトするビットを使用して分割したり、ポインター演算を使用してクラスメンバーにアクセスしたり、一部のプールされたオブジェクトにカスタムメモリアロケーターを使用したりします。

2. 擬似コード（つまり、コメント）を最初に記述し、ルーチン/メソッド/関数の記述が終了したら、実際のコードを記述します。使用されている言語は高レベルでありながら特定であるため、かなり冗長になる可能性があります

3. コードを記述する前でも、コードが何をしているのかを把握する

4. 実際のコードに近いコメントを付ける

目標は、古くなっている可能性のある関係のない長いコメントを避けることですが、コードの意図と目的を反映したコメントを持つことです。高レベルの擬似コードを使用すると、実装を記述する前に考えを明確にするのにも役立ちます。

この本を追跡したくない場合のために、GameDev.netには[PDLを説明する] [1]のリンクがあります。

私はただ一つの単純で一般的な原則に従うだけです。あなたのコメントはコードが何をしているのかではなく、なぜそれをしているのかを言うべきです。Martin Fowlerの 記事とリファクタリングとコードの完全な本には多くの情報がありますが、残念ながらそれは要約された形ではありません。

私の提案は、コメントなしでいくつかのコードを記述し、それから離れることです。1年後にそれに戻って読んでください。簡単に理解できない部分は、コメントすべき部分です。

Evan Toddが唯一の有用なコメントカテゴリ（彼のブログから引用）に関する彼の見解を要約する方法が本当に好きです。

• 何ではなく、理由を説明するコメント。これらは最も便利です。
• 次の巨大なコードが何をするのかを説明するいくつかの単語を含むコメント。これらは、ナビゲーションと読み取りに役立ちます。
• 各フィールドの意味を説明する、データ構造の宣言内のコメント。多くの場合、これらは不要ですが、概念をメモリに直感的にマッピングすることができない場合があり、マッピングを説明するためにコメントが必要です。