関数が文字列を返すことを伝えるためだけに、画面の半分をアスタリスクで埋めるコメントが嫌いでした。私はそれらのコメントを読んだことがありません。
ただし、何かが行われる理由とその方法を説明するコメント (通常はコード内の 1 行のコメント) は読みます。これらは、他の人のコードを理解しようとするときに非常に役立ちます。
しかし、コメントを書くことになると、私はそれを書きません。むしろ、プログラミングコンテストでアルゴリズムを書くときにのみコメントを使用します。アルゴリズムがどのように動作するかを考えてから、それぞれをコメント、そのコメントに対応するコードを記述します。
例は次のとおりです。
//loop though all the names from n to j - 1
それ以外では、コードを書いている可能性があるのに、コメントを書くために貴重な時間を無駄にする理由が想像できません。
私は正しいですか、それとも間違っていますか？何か不足していますか？私が認識していないコメントの他の良い使用例は何ですか?
コメントは、何をしているのかではなく、なぜそれをしているのかを表現する必要があります
古い格言ですが、使用するのに適した指標は次のとおりです。
どのように行っているかではなく、なぜそれを行っているかをコメントしてください。
「n から j-1 までのすべての名前をループする」ということは、初心者のプログラマーでもコードだけですぐに理解できるはずです。その理由を説明すると、読みやすくなります。
Doxygenのようなものを使用すると、戻り値の型、引数などを完全に文書化して、優れた「ソース コード マニュアル」を生成できます。私のコードを継承するチームが完全に失われないように (または、すべてのヘッダーのレビューを強制されないように)、私はしばしばクライアントに対してこれを行います。
ドキュメンテーション ブロックはしばしばやり過ぎです。特に、強く型付けされた言語はそうです。C++ や Java よりも、Python や PHP などで冗長にする方がはるかに理にかなっています。そうは言っても、自明ではないメソッドとメンバー (たとえば、update という名前ではない) に対して行うのはまだ良いことです。
初めて自分のコードを読んだ場合に自分に言いたいことをコメントするだけで、何時間も考える時間を節約できました。物語性が高く、観察が少ない。コメントは他の人だけでなく、自分自身にも役立つはずです... 特に 5 年間触れていない場合はなおさらです。私は自分で書いた 10 年前の Perl を持っていますが、それが何をするものなのかまだわかりません。
私が PHP と Python で行った非常に厄介なことは、リフレクションを使用して、ユーザー インターフェイスでコメント ブロックとラベル要素を取得することです。厄介ですが、それはユースケースです。
バグ トラッカーを使用している場合は、バグ ID を変更の近くにドロップして、トラッカーを参照できるようにします。これは、変更の簡単な説明 (インライン変更ログ) に追加されます。
また、同僚がめったに見ないことをしている場合や、微妙さが重要な場合は、「コメントのみ」というルールに違反しています。例えば：
for (int i = 50; i--; ) cout << i; // looping from 49..0 in reverse
for (int i = 50; --i; ) cout << i; // looping from 49..1 in reverse
次の状況でコメントを使用します。
簡単ではなく、次にコードを見たときに理解できないと思うものはすべてコメントしてください。
自分のコードが達成すべきだと思うことを記録するのは悪い考えではありません(特に、コードが直感的でない場合や、コメントを最小限に抑えたい場合)。デバッグ/バグ修正。他人のコードを読む際に遭遇する最も苛立たしいことの 1 つは、コードが更新されているのにコメントが更新されていない場合です....
関数が文字列を返すことを伝えるためだけに、画面の半分をアスタリスクで埋めるコメントが嫌いでした。私はそれらのコメントを読んだことがありません。
JavaDoc や Doxygen などのツールがコードのドキュメントを生成するのを助けるために、通常は極端な書式設定ではなく、そのようなコメントが実際に存在します。これは、人間が読める形式と機械が読める形式の両方のドキュメンテーションを備えているため (機械が HTML などの他のより便利な形式に変換できるため)、良い形式のコメントだと思います。ドキュメンテーションをコードに近づけます。それが文書化されていること (コードが変更された場合、これらの変更を反映するように文書が更新される可能性が高くなる)、一般に、特定の関数が存在する理由について、大規模なコードベースに慣れていない人に適切な (そして即時の) 説明を提供します。
それ以外の場合は、記載されている他のすべてに同意します。理由をコメントし、それが明らかでない場合にのみコメントしてください。Doxygen コメントを除いて、私のコードには一般的にコメントがほとんどありません。
少し前にこのコメントを書きましたが、それ以来、何時間も節約できました。
// NOTE: the close-bracket above is NOT the class Items.
// There are multiple classes in this file.
// I've already wasted lots of time wondering,
// "why does this new method I added at the end of the class not exist?".
一般的に役に立たない別の種類のコメントは次のとおりです。
// Commented out by Lumpy Cheetosian on 1/17/2009
...うーん、OK、ソース管理システムが教えてくれたはずです。それが私に教えてくれないのは、なぜLumpyがこの一見必要なコードをコメントアウトしたのかということです. ランピーはエルボニアにいるので、スナークランプのホリデー フェスティバルから全員が戻ってくるのは月曜日になるまでわかりません。
聴衆を考慮して、騒音レベルを低く抑えてください。コメントに無関係ながらくたが含まれている場合、開発者は実際にはそれらを無視します。
ところで：Javadoc（またはDoxygen、または同等のもの）はGood Thing（tm）、IMHOです。
また、コメントを使用して、特定の要件がどこから来たのかを文書化します。こうすることで、開発者は後でコードが元のようになる原因となった要件を調べることができ、新しい要件が他の要件と競合する場合は、既存のプロセスを壊す前に解決することができます。私が働いている場所では、システムが満たさなければならない他の要件を認識していない可能性のあるさまざまなグループの人々から要件が寄せられることがよくあります。また、なぜ特定のクライアントに対して特定の方法で特定のことを行っているのかという質問も頻繁に寄せられます。追跡システムのどのリクエストが原因でコードがそのようになったのかを調査できることは役に立ちます。これはソース管理システムにコードを保存する際にも実行できますが、それらのメモもコメントであると考えています。