少し前にコードレビューを組織したとき、コードの可読性の問題に関して多くの人が最初に反応したのは、さらにコメントを追加することでした。そして、注釈はおまけにすぎず、雪の中の贈り物ではないといつも感じています。コメントがいくらあってもコードの論理構成が混沌としていることは変わりませんが、逆にコメントが多すぎるとコードを読む時間が長くなります。
適切に配置されたコメントほど役に立つものはありません。ごちゃ混ぜのコメントほどモジュールを台無しにするものはありません。古くなって誤った情報を提供するコメントほど破壊的なものはありません。
コメントは必要悪であり、プログラミング言語の表現力が足りない場合にのみ、コメントを使ってコードの意味を説明する必要があります。コメントを適切に使用すると、コードで意図を表現できなかったことを補うことができます。コメントを書く必要がある場合は、コードで表現できるかどうかを検討してください。
アノテーションのもう 1 つの致命的な欠点は、アノテーションが必ずしも正しいとは限らないことです。他の人のコードを変更するときにそのコメントを見ると、コメントを変更しない可能性が非常に高くなります。時間の経過とともに、コメントされたコードの意味は変化しましたが、コメントはコードのメンテナンスとともに維持されていません。
1. コメントは悪いコードを美化することはできません
コメントを書く一般的な動機の 1 つは、不正なコードの存在です。
少数のコメントを含むクリーンで表現力豊かなコードは、多数のコメントを含む断片的で複雑なコードよりも読みやすく、保守しやすいです。
2. コードを使用して説明する
たとえば、次のコードですが、どれを見たいですか:
3. 良いメモ
いくつかのコメントは必要かつ有益です。しかし、本当に良いコメントは、コメントなしで表現できるものだけです。
3.1 法的情報
3.2 必要な情報を記載したメモ
3.3 意図の解釈
注釈は、実装に関する有用な情報だけでなく、特定の決定の背後にある意図も提供する場合があります。
3.4 解釈
コメントは、不明瞭なパラメータや戻り値の意味を読みやすい形式に変換することがあります。通常、パラメータや戻り値自体を十分に明確に表現するよう努めますが、戻り値やパラメータが標準ライブラリの一部であり、ソース コードを変更できない場合は、コメントを使用して説明することができます。
3.5 警告
例外の結果について他のプログラマに警告するために使用されます。
3.6 ToDo メモ
ToDo は、プログラマがやるべきだと考えているのに、何らかの理由でまだ実行されていない作業の一種です。
3.7 ズームイン
不合理に見えるものの重要性を強調するために使用されます
3.8 パブリック API の Java ドキュメント
この種のアノテーションは、JDK ソース コードや Spring ソース コードでよく見られます。
4. 悪いコメント
ほとんどのコメントは悪いコメントです。多くの場合、悪いコメントは、悪いコードに対する支持および言い訳、または悪い決定に対する修正であり、基本的にプログラマーの独り言と同じです。
4.1 つぶやき
コメントを追加すべきだと思うから、またはプロセスでコメントを追加する必要があるからといって、コメントを追加しても意味がありません。コメントを書くことにした場合は、適切なコメントを書くために必要な時間をかけてください。
4.2 冗長なコメント
たとえば、次のコード:
コメントはコード自体以上の情報を提供できません。
4.3 誤解を招く注記
書かれたコメントが十分に正確でない場合、コードを読む人に誤解を与える可能性があります。
4.4 適合コメント
すべての関数に Javadoc コメントが必要である、またはすべての変数にコメントが必要であるといういわゆるルールにより、コードが煩雑になることがよくあり、コードを反復するときにコメントが更新されないと、コードの理解を誤解させることになります。
4.5 記録されたコメント
コードを編集するたびにモジュールの先頭にコメントを追加する人がいますが、この種のコメントは、すべての変更を記録する一種のログのようなものです。このような注釈:
4.6 でたらめなメモ
4.7 位置マーカー
プログラマーは、次のようなコード内の特別な場所にマークを付けたがる場合があります。
4.8 括弧の後の注記
4.9 帰属と署名
4.10 コメントアウトされたコード
コードを直接コメントアウトするのは悪い習慣です。プログラムを保守する人は、コメント化されたコードをあえて削除せず、コメント化されたコードが山積みになり、コードの読み取りに支障をきたすため、コードの保守や読み取りには不向きです。
4.11 HTMLコメント
4.12 非地域情報
コメントを書く場合は、コメントに最も近いコードが記述されていることを確認してください。
4.13 情報が多すぎる
4.14 自明ではない接続
コメントとコメントで説明されているコードとの関係は、少なくとも読者がコメントとコードを見て、コメントが説明している内容を理解できるように、明確である必要があります。
4.15 関数ヘッダー
関数には多くの説明は必要ありません。通常、関数に適切な名前を付ける方が、関数ヘッダーにコメントを付けるよりもはるかに優れています。
4.16 非公開コードの Javadoc
Javadoc はパブリック API にとっては非常に便利ですが、パブリック使用としてカウントされないコードにとっては扱いにくくなります。システム内のクラスや関数の Javadoc ページを生成することが常に役立つとは限らず、Javadoc コメントの追加の形式要件はステレオタイプの記事とほぼ同等です。
まとめ：
- 関数または変数を使用して説明できる場合は、コメントを使用しないでください。
- コメントを追加する必要がある場合は、まずコードを再編成して適切な関数名または変数名を付けることができるかどうかを検討してください。
- コメントは必要な場合にのみ追加されます。