A Philosophy of Software Design ch12 Why Write Comments? -- The Four Excuses
Why Write Comments? -- The Four Excuses
- コードコメントは正しく書けばシステムの設計を向上させる
- 開発者がシステムを理解しやすくし、効率的に仕事できるように
- 抽象化
- コメントなくして複雑性を隠蔽することはできない
- 正しく書かないと無駄な重荷になることも事実
- 多くの開発者が書き方をわかっていない
- 良いコメントを書くことは難しくないし、楽しい
- 書かない言い訳4選
- 良いコードはコード自身がドキュメントになる
- 書く時間がない
- コードに対して古くなり、誤解を生むようになる
- 今まで見てきたコメントは無価値だった
- これらを論破していく
Good code is self-documenting
- モジュールのインタフェースの情報には2種類ある(Ch.4 p.21より)
- formal
- メソッドのシグネチャ
- 変数名
- 【補】言語機構の
interface
- informal
- コメントとか
- formal
- formalで表現できることには限りがある
- formalで表現できないことはinformalで表現せざるをえない
- 「実装を読め」「実装はどんなコメントよりも正確」に対する反論
- 時間がかかるし苦痛
- 読まれることを念頭に置いた実装になるため、浅いメソッドが大量に生えがち
- シグネチャから「何をするか」が自明でないメソッドは分割されるため
- Ch.4 Modules Should Be Deep に反する
- 大きなシステムでは非現実的
- 利用者がメソッドの実装を読まなければならないということは、抽象化できていないということ
- 自然言語(英語等)で書かれていることが肝要
- 単純で直感的な説明を記述できる
- コードと比べて、正確性で劣るが、表現力で勝る
- 単純で直感的な説明を記述できる
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
- 設計思想のうち、コードで表現できない情報をコメントに込める
- 低水準の詳細
- 例: 癖のあるハードウェアのためにトリッキーなコードが必要になった
- 高水準の概念
- 例: クラスの理論的根拠
- 低水準の詳細
- 【補】きのこ56: 未来へのメッセージ
- 将来、他の開発者が参入し、コードに変更を加えることになる
- 数週間後の自分かもしれない
- コメントがあると
- 素早く
- 正確に仕事にかかれる
- コメントがないと
- 前任者の意図を汲み取るのに時間がかかり
- 誤解によるバグ埋め込みのリスクもある
- 将来、他の開発者が参入し、コードに変更を加えることになる
- 複雑性の減少
- 複雑性の3つの柱(再掲)
- 変更の増幅
- 認知の負荷
- わからないことがわからない
- よいドキュメンテーションは、最後の2つを減らす
- 認知の負荷
- モジュールの変更に必要な情報を提供する
- 関係のない情報を無視しやすくする
- 【補】実装を覗きにいかなくてよい
- わからないことがわからない
- システムの構造を明確化する
- ドキュメントとコードとの紐付けが明確になる
- 認知の負荷
- 複雑性の3つの柱(再掲)
- 複雑性の主要な原因の排除
- 複雑性の原因(再掲)
- 依存
- 不明瞭
- よいドキュメンテーションは、依存を明確化し、不明瞭さを排除する
- 複雑性の原因(再掲)
英語
- prevalence
- 広く知られている
- drudge
- Verb: 骨の折れる仕事をこつこつ行う
- Noun: こつこつ働く人
- why bother
- ...する必要はない
- 反語的
- ...する必要はない
- solid
- 中身のある？
- worthlessの対義語的に使われているので多分これ
- 中身のある？
- quirk
- くせ
- debunk
- 嘘であることをあばく
