Why Write Comments? The Four Exercises
「コメントを書かない4つの言い訳 と コメントの重要性」
コードにおけるコメントの役割
開発者がシステムを理解し、効率的に作業するためのドキュメント コメントがなければ、複雑さ を隠蔽することは不可能 コメントを正しく書くと、システム設計の改善につながる
ただし、不十分なコメントは逆に足かせとなる
開発者がコメントを書くのを避ける4つの言い訳
コメントを書く暇がない（I don't have time to write comments.）
コメントが古くなると誤解を招く（Comments get out of date and become misleading.）
今まで見てきたコメントはすべて無価値だった（The comments I have seen are all worthless.）
正しくコードを書いていれば、コメントを減らすことはできる
しかし、コードで表現できない設計に関する情報は数多くある
メソッドが何を行うか、なぜそれを行うか
メソッドが意味を持つ（処理を行う）条件
ある設計上の決定理由 etc ...
「メソッドの振る舞いを知りたければ、実装を読めば良い」という主張
大規模開発では不可能
実装を読むのは、時間がかかる上に苦痛を伴う行為
実装を読むことを想定すると、メソッドをできるだけ短くしようとする
結果、トップレベルのメソッドの振る舞いを理解するために、幾層にもネストした Shallow Method の振る舞いを理解する必要が出てくる 抽象化 = 複雑な物事について考えたり、操作したりすることを簡単にしてくれるもの
ユーザがメソッドを使うためにそのコードを読まなければいけないとしたら、それは抽象化とは言えない コメントの無いメソッドは、抽象化には多くの重要な情報を欠いている メソッド名と、引数や戻り値の名前や型に関する情報しか存在しない
e.g. 部分文字列を取得するコード
引数: 部分文字列の範囲を示す2つの値（start, end）
以下のことを知ることができない
end を含むかどうか
start > end の場合にどうなるか
また、自然言語で記述できるので、コードよりも正確性に欠けるが表現力が増す コメントを書く暇がない
良いコメントはソフトウェアの保守性にも影響をもたらすので、費やした労力はすぐペイできる コメントを書くのに多くの時間を費やすことは無い
良いコメントを書くにしても、開発時間が 10% 以上増えることは無い
コメントを書くのを、設計プロセスの一部に組み込む
クラスやメソッドのトップレベルのコメントは特に重要
この行為は、設計全体を改善する重要な設計ツールとして機能する
コメントが古くなると誤解を招く
コメントを最新に保つことは、そこまで労力を必要としない
コメントを大きく変更する場合は、コードに大きな変更があったとき
コードの変更に費やす時間 >>> コメントの変更に費やす時間
コメントを簡単に更新できるように整理する方法
コメントの重複を避ける
コメントを対応するコードの近くに置く
コードレビューで古くなったコメントを検出する
今まで見てきたコメントはすべて無価値だった
良いコメントを書く方法は、方法さえ知っていれば難しいことではない
今まで見てきたコメントは、その方法を知らないで書かれたコメントである radish-miyazaki.icon
良いコメントのメリット
コメントは「実装時に開発者の頭の中にあるが、コードで表現できなかった情報を共有する」ためのもの
他の開発者や自身が後で変更するとき、迅速かつ正確に作業できるようにする
コメントが無いと、元の開発者の意図を推測する必要があり、誤解のリスクがある
開発者が変更するのに必要な情報を提供し、無関係な情報を無視できるようにすることで、認知的負荷を減らせる システム構造に関する情報を提供し、変更の影響範囲がどの情報やコードに及ぶのかを明確にすることで、未知の未知を減らせる