Why Write Comments? — The Four Excuses
-
コードコメントは正しく書けばシステムの設計を向上させる
- 開発者がシステムを理解しやすくし、効率的に仕事できるように
-
抽象化
- コメントなくして複雑性を隠蔽することはできない
-
正しく書かないと無駄な重荷になることも事実
- 多くの開発者が書き方をわかっていない
- 良いコメントを書くことは難しくないし、楽しい
-
書かない言い訳4選
- 良いコードはコード自身がドキュメントになる
- 書く時間がない
- コードに対して古くなり、誤解を生むようになる
- 今まで見てきたコメントは無価値だった
- これらを論破していく
Good code is self-documenting
-
モジュールのインタフェースの情報には2種類ある(Ch.4 p.21より)
-
formal
- メソッドのシグネチャ
- 変数名
- 【補】言語機構の
interface
-
informal
- コメントとか
-
- formalで表現できることには限りがある
-
formalで表現できないことはinformalで表現せざるをえない
-
例
- 設計上の決定事項の理論的根拠
-
特定のメソッドを呼び出す事前条件
- 【補】Value ObjectやEnum等の不変条件である程度縛れるけど…
-
-
「実装を読め」「実装はどんなコメントよりも正確」に対する反論
- 時間がかかるし苦痛
-
読まれることを念頭に置いた実装になるため、浅いメソッドが大量に生えがち
- シグネチャから「何をするか」が自明でないメソッドは分割されるため
- Ch.4 Modules Should Be Deep に反する
- 大きなシステムでは非現実的
-
利用者がメソッドの実装を読まなければならないということは、抽象化できていないということ
- 抽象とは、ある実体から、必要な情報を保ちつつ、不必要な詳細を省いたもの
- コメント無しでシグネチャだけでは必要な情報を表現しきれない
-
例:
start
とend
引数をとるメソッド[start, end]
なのか[start, end)
なのか-
start > end
になったらどうなるのか-
【補】例外送出?
- どんな例外?
- 【補】長さ0の区間として扱う?
-
-
自然言語(英語等)で書かれていることが肝要
-
単純で直感的な説明を記述できる
- コードと比べて、正確性で劣るが、表現力で勝る
-
I don’t have time to write comments
-
Ch.3 Working Code Isn’t Enough の繰り返し
- 既存の機能のドキュメンテーションは、新機能開発よりも優先度が下がりがち
- とはいえプロジェクトはほぼ常に時間に追われている
- 優先度を下げたが最後、ドキュメンテーション無しに終わる
-
コメントを書くのに時間はそうかからない
-
開発時間に占める「タイピング」の時間はどれほどだろう
- 設計、コンパイル、テスト等除く時間
-
コメントを全く書かなかったとして、高々10%程度だろう
- 【所感】もうちょい長い気がするけど…今度測定してみよう
- 仮定: コメントのタイピング量は、高々コードのタイピング量と同程度
- コメントのタイピング時間は、全開発時間のうち高々10%ということになる
- よいドキュメンテーションがもたらすメリットで、すぐ元を取れる
-
-
抽象化にまつわる重要なコメント
- クラスやメソッドのトップレベルのコメント等
-
書く行為自体が重要な設計ツールとなるので、即座に元を取れる
- Ch.15にて詳しく論ずる
Comments get out of date and become misleading
-
実際に問題になることは少ない
- コードに大きな変更があって初めて、ドキュメントにも大きな更新が必要になる
- ドキュメントの更新よりもコードの変更のほうが時間がかかる
- Ch.16にて、コード変更に追従しやすいドキュメントの作り方について論ずる
- コードレビューは、腐ったコメントを発見し修正するための素晴らしい仕組みである
All the comments I have seen are worthless
- 中身のあるドキュメントを書くことは、やり方さえわかれば難しくない
- 次章にて、よいドキュメントの書き方と維持のしかたのフレームワークを提示する
Benefits of well-written comments
-
設計思想のうち、コードで表現できない情報をコメントに込める
-
低水準の詳細
- 例: 癖のあるハードウェアのためにトリッキーなコードが必要になった
-
高水準の概念
- 例: クラスの理論的根拠
-
-
-
将来、他の開発者が参入し、コードに変更を加えることになる
- 数週間後の自分かもしれない
-
コメントがあると
- 素早く
- 正確に仕事にかかれる
-
コメントがないと
- 前任者の意図を汲み取るのに時間がかかり
- 誤解によるバグ埋め込みのリスクもある
-
-
複雑性の減少
-
複雑性の3つの柱(再掲)
- 変更の増幅
- 認知の負荷
- わからないことがわからない
-
よいドキュメンテーションは、最後の2つを減らす
-
認知の負荷
- モジュールの変更に必要な情報を提供する
-
関係のない情報を無視しやすくする
- 【補】実装を覗きにいかなくてよい
-
わからないことがわからない
- システムの構造を明確化する
- ドキュメントとコードとの紐付けが明確になる
-
-
-
複雑性の主要な原因の排除
-
複雑性の原因(再掲)
- 依存
- 不明瞭
- よいドキュメンテーションは、依存を明確化し、不明瞭さを排除する
-
英語
-
prevalence
- 広く知られている
-
drudge
- Verb: 骨の折れる仕事をこつこつ行う
- Noun: こつこつ働く人
-
why bother
-
…する必要はない
- 反語的
-
-
solid
-
中身のある?
- worthlessの対義語的に使われているので多分これ
-
-
quirk
- くせ
-
debunk
- 嘘であることをあばく