A Philosophy of Software Design ch15 Write The Commnts First (Use Comments As Part Of The Design Process)
Write The Commnts First (Use Comments As Part Of The Design Process)
- 多くの開発者は、ドキュメンテーションを開発プロセスの最後まで先延ばしにする
- コーディング、テストの完了後
- かくして低品質なドキュメントは生まれる
- コードコメントはコーディングの最初に書け
- コメントを書くことが設計プロセスの一部になる
- 効能
- よいドキュメント
- よい設計
- ドキュメンテーションが楽しくなる
Delayed comments are bad comments
- なぜコメントを先延ばしにするのか
- 「コードが変化したら書き直しになるから、コードが安定してから書く」
- 本当にそれだけか?
- コメントを書くことが、単調で骨の折れる仕事だと思っているから先延ばしにするのでは?
- コメントの先延ばしは良くない結果をもたらす
- 永久に書かれない
- コードが安定するのを何週間も待っているうちに、書かなければならない量が膨大になる
- よりいっそう書きたくなくなる
- コメントを埋めるために何日も立ち止まっていられない
- バグフィックスなり新機能実装なり、どんどん前に進むほうが正当化されやすい
- たとえ書いたとしても、あまりよいコメントにならない
- さっさと次に進みたいので、「それらしい」コメントを書くにとどまる
- 設計・コーディングしてからしばらく時間がたっているため、記憶が定かでない
- コードを追いながら書くため、コードと同じことを繰り返すだけのコメントになりがち
- コードに現れない設計思想はコメントに反映されない
- 設計者ももう覚えていない
- 永久に書かれない
Write the comments first
- 著者のアプローチ: 一番最初にコメントを書く
- コーディング完了とともに、コメントも完了する
- 3つの利点
- 良いコメントになる
- 設計課題について、記憶が新しいうちにコメントとして記録できる
- 実装をまだ書いていないうちにコメントを書くので、実装に惑わされずインタフェースを記述できる
- コーディング・テストプロセス通じてコメントを修正するので、コメントの質が上がる
- 残り2つは次節以降
- 良いコメントになる
Comments are a design tool
- 2つめの利点
- コメントは抽象を完全に捉える唯一の方法
- 【補】抽象=インタフェースの記述方法にはformal/informalがある
- formal: シグネチャ等
- informal: コードコメント
- formalだけでは完全には記述できない
- 【補】抽象=インタフェースの記述方法にはformal/informalがある
- コメントから書くということは、抽象から書くということ
- 実装にとりかかる前に抽象をレビュー・調整できる
- これから書く変数やスニペットの本質をこめる
- コメントは複雑性の警告
- 長いコメントが必要ということは、抽象化がよろしくないということ
- 【補】「重要でない詳細」を削ぎ落とせていないから長くなる
- インタフェースコメントには、利用側が必要とする全ての情報が含まれており、かつ短く簡潔であること
- 単純なインタフェースで多くの機能、Deep Module
- 逆はShallow Moduleでよろしくない
- インタフェースが複雑なわりに、大した機能を提供しない
- メソッドのインタフェースコメントと実装とを比較してみよ:
- インタフェースコメントが実装の全機能を説明しなければならない場合、そのメソッドは「浅い」
- 変数も同様
- 長いコメントが必要ということは、抽象化がよろしくないということ
- コメントを最初に書くことで、設計を早期に見直し、修正できる
Early comments are fun comments
- 3つめの利点
- 著者にとって一番楽しいのは初期の設計フェーズ
- 設計の良し悪しがコメントの単純さとして現れるので楽しい
Are early comments expensive?
- コメント先延ばし派の言い分は「コードが変わるとコメントも書き直しになるから、コードが安定するまで書かない」
- 「コメントを書き直さなかった」ことで回避できるコストはいかほどのものか?
- コメントから書くと時間がかかる?
- むしろ時短するまである
- インタフェースコメント=抽象が固まってから実装に取り掛かるので、実装の手戻りを防げる
- むしろ時短するまである
Conclusion
- 「コメントを最初に書く」、試してみてほしい
- 慣れるまで十分時間をかけて
- コメント・設計の質、開発の楽しさにどう影響したか考えてほしい
- このスタイルが合ったか否か、それはなぜか、著者に教えてほしい
英語
- move on
- どんどん進む
- respectable
- りっぱな
- canary in a coal mine
- 警告、予兆
- 炭鉱でカナリアを飼って、有毒ガスを検知したことから
- 警告、予兆
- back-of-the-envelope calculation
- (封筒の裏に走り書きするような)大雑把な計算