コードでコメントを書く最良の方法
コードでコメントをどのように書くべきか疑問に思っていました。つまり、コメントは次のようにコードで行われることを説明するものでなければなりません：//we have got array, now we iterate over it. code to iterate array
それともここで何をすべきかを教えているのでしょうか。注文のように：//we have got array, iterate over it. code to iterate array
コードの概要。それを書くときは明らかかもしれませんが、2年後ではないので、このコードがアプリケーションで使用されるとき、それが使用される理由などを書き留めてください。 「このコードは、ユーザーがポストで失われた返却パッケージについて文句を言うフォームに記入する状況を処理します」のように。 「このコードの目的は何なのか」という質問に答えます。
明らかでない場合は、コードの動作の概要を説明します。
ヘッダーファイル（またはそれらが自動的に抽出される場所）内のコメント。これにより、すべてのパブリック関数について、リーダーは、ソースコードを参照せずに、その機能とその理由を知ることができます。
特に仮想関数の場合：オーバーライドを含むこの関数が実行するはずのヘッダーファイル内のコメント。非仮想関数の場合、コメントは便利なため、ソースコードを読む必要がありません。仮想関数の場合、ソースコードはありません。
奇妙に見えることを他の開発者に知らせるコメント。私のコードに、まったくナンセンスに見える行がいくつか含まれている箇所があり、その後、「ライブラリXYZのバグを回避する」というコメントがあります。
解決される問題に関してコードが何をするかを説明するコメント。 「昨年に100ドル未満の商品を購入して3回以上返品したすべての顧客を見つける」のように、これはコードからは明らかではないかもしれません。
配列を反復処理するコードのコメントはナンセンスであるため、「配列を取得しました。反復処理を行います」。あなたが繰り返していることがわかります。コメントは必要ありません。反復が実際に行っていることを教えてください。
どちらでもない。コメントはwhatコードを記述すべきではなく（コード自体と同じ抽象化レベルで）、-whyのみが何かを行います
これを文字どおりに受け取らないでください。これはガイドラインです。短い要約を作成した場合長いコードが実行するので、それは許容される場合があります。ただし、「これは反復です」などの明らかなことを説明するコメントは避けてください。コードを読みやすくしたり理解しやすくしたりせず、余分なものを追加するだけで、DRYの原則に違反しています。
あなたが書いたコメントは、初心者のために新しい言語を教えるときのデモコードに適しています。これらは、「ジェーンの実行を参照してください。実行、ジェーン、実行！」に相当します。
しかし、他のすべての設定では、それらは適切ではありません。すべての常習的なプログラマーは、「ええ？何が起こっているのかすでに完全に明らかなのに、なぜ私にこれを言っているのですか？私が見逃している明白でない何かが起こっているのですか？」と考えて戸惑うでしょう。
小説の著者は、「ジェーンは建物を離れ、通りを歩いて、体系的に片方の足をもう一方の前に置きました」とは書いていません。彼は「ジェーンがデパートに行った」、または「ジェーンがデパートに到着したとき、彼女は...」または「単に買い物を終えて、ジェーンはリラックスした...」とさえ書いた。
同様に、プロのプログラマーは書きません
// Iterate over the array
for(int x: ai) { ...
しかしせいぜい
// notify all observers
for(int x: ai) { ...
それとも
notifyObservers()
実際のコードは、わかりやすい名前のサブルーチンに隠されています。
コメントは、コードを読んだだけでは明らかではない、コードを使用または保守している将来の開発者に情報を伝えるためのものです。
コメントを書くときは、コードに慣れていない新しい開発者が直面している状況と現在の考え方を考慮してください。
コードを書いている間、あなたは通常、頭の中でたくさんのボールをジャグリングして、潜在的な落とし穴を避けようとしています。そして、コメントはあなたがジャグリングしているものを反映しているべきです。なぜならそれは将来の開発者も間違いをすることを避けるために知る必要がある情報である可能性が最も高いからです。例えば：
// A user could potentially type an invalid username here but we can't // validate it yet because we need to support the legacy login format.
または
// We don't know whether the server is available yet, but we don't care // until the user does something which involves a message to the server.
または
// Always use the FooFactory for creating Foo objects because it guarantees // they will be initialised using the correct Config.
または
// This calculation is only an approximation until the customer can // supply us with the correct logic, so we know it's wrong, but the // customer confirmed they are happy with it as an interim measure.
または
// HACK: this function fixed a critical fault identified while on XYZ customer site. // This is currently in use by XYZ, it must be refactored into a generic solution ASAP. // see ticket #12345 in the bugtracking system.
または
// This function may fail if VehicleType==Train, but there are currently no // documented requirements or data for Trains, so there's no way to reliably test it.
したがって、コードに挿入するコメントの種類を決定するときは、コード自体からいくつかのステップを取り、直面したすべての問題、発生した想定、発生した妥協などについて考えてください。
コメントは、「なぜこの特定の時期にこの特定の方法でこのコードを書いたのか」を説明する根拠である必要があります。実際は、コードは通常決して'finished'ではなく、コードは常に進化する傾向があり、現実世界の問題（期限、顧客の要求、予算など）によって制約される傾向があります。そのため、開発者の制御が及ばないイボや欠陥が常に存在します。
あなたのコメントはそれらのことを文書化するのに最適な場所です-長いエッセイを書くのを避け、間違いをしないように将来の開発者に警告するかもしれない最小限の情報に固執するか、または単に利点/制限を考慮したことを彼らに知らせてくださいあなたのソリューションの（または誰かが他の人の既存のコードで潜在的な問題を発見し、それを修正することができなかったとしても）。
あなたの具体的な例に対する答えはどちらでもないと思います。コメントはコードが何をするかを説明すべきではありません。コードはコードが何をするかを説明するべきです。コメントは、それがなぜそれを行うのかを本当に説明するべきではありません。それは、わずかなドメイン知識でも技術知識でも明らかであるべきです。
この2番目の部分は時々難しいです。ときどき、使用しているフレームワークに不明瞭なバグや非常に奇妙な癖が見つかることがあります。 「明らかにより良いコード」は、現在の奇妙に見えるコードよりも実際には悪いかもしれません、そしてそれらの場合にはもちろん例外を作り、状況を説明するコメントを追加することは問題ありません。
ただし、これは失敗と見なす必要があります。他の人が言及したように、コメントはほとんど冗長であるため、これは回避すべきものです。 VERYが実際に値を与えることはほとんどありません。しかし、違反DRYは最悪の部分でもありません。コメント付きの最悪の部分は、それらがコードではないため、実行されないため、読者がコメントに何かがあるという証拠はありません現実と全く関係ない。
コメントは古くなり、間違いがあり、孤立し、作者が間違っている可能性があります。 「このコードブロックはXを実行します」というコメントが表示された場合でも、Xを実行していることを確認せずに信頼することはできません。
コードのアルゴリズム構造が一目でわかりにくいと感じた場合の解決策は、20件のコメントを追加しないことです。それは、コードを再構成/リファクタリングして、適切なメソッド名を持つ小さな簡潔な論理ユニットに分離することです。私たち全員が学習したパターンを使用してください。カプセル化します。良いアーキテクチャを設計します。ポストイットをあちこちに貼り付けて、悪いアーキテクチャを隠さないでください。
編集：一部の人々は誤解しているように見えるので、明確にするために：私はあなたがコメントを決して使用すべきではないと言っていません。彼らは多くの問題をもたらすので、あなたは本当に本当に本当にしたくないのだと言っています。私は時々あなたがしなければならないことを言っていますが、あなたはより良い解決策を見つけるように努めるべきです。