第4章[Clean Code]|注釈

🧷 第4章|コメント
悪いコードにコメントをつけないでください.再編成しましょう.議長はせいぜい必要な悪だ.

私たちはコードで意図を表現できないためにコメントを使用します.コメントは常に失敗を意味します.

注釈が長くなるほど、コードから遠くなります.

不正な注釈はまったくない注釈よりずっと悪い.真実は一つの場所にしか存在しない.これがコードです.

→そのため、コメントをできるだけ少なくするように努力します.
📘 注記悪いコードを補うことはできません.
コードにコメントを追加する一般的な理由は、コードの品質が悪いためです.
表現力が豊富で、簡潔で、注釈がほとんどないコードは、複雑で、乱れていて、注釈の多いコードよりずっと良いです.
📘 コードで意図を表す!
多くの場合、コメントする説明を関数で表すことができます.
悪い例)

// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flags & HOURLY_FLAG) && (employee.age > 65))

良い例)

if (employee.isEligibleForFullBenefits())

📘 よい議長
本当に良い注釈は、注釈をつけない方法を見つける注釈です.

法的コメント
ex)著作権情報、所有権情報等の法律情報(ソースファイルの先頭にある注釈)

情報を提供するコメント
ex)正規表現を変換する意味→視点と日付のクラスを作成することでコードを移動すると,より簡潔になる.

関数の実装意図を説明するコメント
ex) return 1; // 정렬 순위가 더 높다

釈義
ex) assertTrue(a.compareTo(a) == 0); // a == a

警告結果のコメント
ex)運転時に注意すべきテストケース→@Ignore属性を使用してテストケースを閉じることができます.

TODOコメント
ex)実施が困難な業務を即時にキャンセルし、問題を見ることを要求し、より良い名前を考え出すことを要求する→定期的にキャンセルする.

重要性を強調するコメント
重要ではないと思われるものの重要性を強調するために

公開APIでのJavaの使用
たとえば,説明のよい公開API→標準Javaライブラリで使用されるJavaを記述することはよい例である.

📘 悪いコメント
ほとんどの注釈はこの範疇です.大部分は粗末なコードを支え、粗末なコードを弁解し、くどくど言う独白である.
あるかどうかにかかわらず、注釈の誘惑から抜け出し、コードを整理しなければならない.より良い、より幸せなプログラマーになる近道です.

小言を言う
ex)理解できません.他のモジュールを検索する必要があるコメントはバイトを無駄にします.

同じ内容のコメントを繰り返す
コードよりも多くの情報を提供できないコメントは無駄です.

コメント
プログラマは、コードよりも読みにくいコメントに含まれるエラー情報を誤導する可能性があります.

義務議長
これらの注釈はコードを複雑にし、嘘をつき、混乱と無秩序をもたらします.

履歴コメント
ソースコード管理システムがあれば、完全に削除したほうがいいです.

コメント
ex)は当然の事実に言及し,新しい情報を提供できない注釈である.

恐ろしい騒音
ex)Javadocsもドキュメントを提供する誤った欲望によって雑音を生じる.

関数や変数で表すことができる場合は、コメントを付けないでください.
ex)コメントを必要としないために、コードを改善することが望ましい.

場所のコメントを表示
exは毒性のみを低下させる.必要に応じて、あまり使わないほうがいいです.

右かっこのコメント
ex)これは,小さくてカプセル化された関数にとってノイズにすぎない.右かっこにコメントを付けるよりも、関数を減らしてみましょう.

コメント
ex)このような情報は、ソースコード管理システムに格納することが望ましい.

コメントコード
ex)ソースコード管理システムは私たちのためにコードを覚えてくれた.注釈はいらないから、削除しましょう.

HTMLコメント
ex)コメントにHTMLタグを挿入する責任はプログラマーではなくツールであるべきである.

グローバル情報
ex)システム全体の情報を記述するためにコード部分に注釈を付けないでください.

情報が多すぎる
ex)興味深い歴史や関連のない情報を注釈に羅列しないでください.

ファジイ関係
ex)コメントとコードは両者の関係を明確にしなければならない.コメント自体は再説明を要求できません.

かんすうヘッド
ex)短い関数は説明する必要はありません.短くて精巧で命名された関数は、ヘッダー注釈関数よりも優れています.

専用コードでのJavadocsの使用
非公開のコードであればJavadocsは役に立たない.