Write The Commnts First (Use Comments As Part Of The Design Process)

• 多くの開発者は、ドキュメンテーションを開発プロセスの最後まで先延ばしにする

  • コーディング、テストの完了後
• かくして低品質なドキュメントは生まれる
• コードコメントはコーディングの最初に書け
• コメントを書くことが設計プロセスの一部になる

• 効能

  • よいドキュメント
  • よい設計
  • ドキュメンテーションが楽しくなる

Delayed comments are bad comments

• なぜコメントを先延ばしにするのか

  • 「コードが変化したら書き直しになるから、コードが安定してから書く」

• 本当にそれだけか？

  • コメントを書くことが、単調で骨の折れる仕事だと思っているから先延ばしにするのでは？

• コメントの先延ばしは良くない結果をもたらす

  • 永久に書かれない

    • コードが安定するのを何週間も待っているうちに、書かなければならない量が膨大になる
    • よりいっそう書きたくなくなる
    • コメントを埋めるために何日も立ち止まっていられない
    • バグフィックスなり新機能実装なり、どんどん前に進むほうが正当化されやすい

  • たとえ書いたとしても、あまりよいコメントにならない

    • さっさと次に進みたいので、「それらしい」コメントを書くにとどまる
    • 設計・コーディングしてからしばらく時間がたっているため、記憶が定かでない
    • コードを追いながら書くため、コードと同じことを繰り返すだけのコメントになりがち

    • コードに現れない設計思想はコメントに反映されない

      • 設計者ももう覚えていない

Write the comments first

• 著者のアプローチ: 一番最初にコメントを書く

  1. 新しいクラスを作るとき、クラスのインタフェースコメントを書く

     • 【補】言語機構のinterfaceのことではない

  2. 重要なpublicメソッドを生やすとき、インタフェースコメントとシグネチャを書く

     • 中身はまだ書かない
  3. 基礎構造が良い感じになるまで繰り返す
  4. 重要なインスタンスメンバ変数の宣言とコメントを書く

  5. メソッドの中身を書く

     • 適宜実装コメントも添える

  6. 追加のメソッドやメンバ変数が必要になったら、コメントファーストで追加する

     • メソッド: インタフェースコメントを書いてから中身を実装する
     • メンバ変数: コメントと宣言を同時に書く
• コーディング完了とともに、コメントも完了する

• 3つの利点

  • 良いコメントになる

    • 設計課題について、記憶が新しいうちにコメントとして記録できる
    • 実装をまだ書いていないうちにコメントを書くので、実装に惑わされずインタフェースを記述できる
    • コーディング・テストプロセス通じてコメントを修正するので、コメントの質が上がる
  • 残り2つは次節以降

Comments are a design tool

• 2つめの利点

• コメントは抽象を完全に捉える唯一の方法

  • 【補】抽象=インタフェースの記述方法にはformal/informalがある

    • formal: シグネチャ等
    • informal: コードコメント
    • formalだけでは完全には記述できない

• コメントから書くということは、抽象から書くということ

  • 実装にとりかかる前に抽象をレビュー・調整できる
  • これから書く変数やスニペットの本質をこめる

• コメントは複雑性の警告

  • 長いコメントが必要ということは、抽象化がよろしくないということ

    • 【補】「重要でない詳細」を削ぎ落とせていないから長くなる

  • インタフェースコメントには、利用側が必要とする全ての情報が含まれており、かつ短く簡潔であること

    • 単純なインタフェースで多くの機能、Deep Module

  • 逆はShallow Moduleでよろしくない

    • インタフェースが複雑なわりに、大した機能を提供しない

  • メソッドのインタフェースコメントと実装とを比較してみよ:

    • インタフェースコメントが実装の全機能を説明しなければならない場合、そのメソッドは「浅い」
    • 変数も同様
• コメントを最初に書くことで、設計を早期に見直し、修正できる

Early comments are fun comments

• 3つめの利点
• 著者にとって一番楽しいのは初期の設計フェーズ
• 設計の良し悪しがコメントの単純さとして現れるので楽しい

Are early comments expensive?

• コメント先延ばし派の言い分は「コードが変わるとコメントも書き直しになるから、コードが安定するまで書かない」

• 「コメントを書き直さなかった」ことで回避できるコストはいかほどのものか？

  • 大したことない

    • 粗く見積もって、コードのタイピング時間は総工数の10%

      • 【補】設計、コンパイル、テスト等除いた、純粋なタイピング時間のことのはず
    • 半分がコメントだとして5%
    • 「書き直さない」ことで回避できるぶんはさらにこの一部分にすぎない

• コメントから書くと時間がかかる？

  • むしろ時短するまである

    • インタフェースコメント=抽象が固まってから実装に取り掛かるので、実装の手戻りを防げる

Conclusion

• 「コメントを最初に書く」、試してみてほしい

  • 慣れるまで十分時間をかけて
• コメント・設計の質、開発の楽しさにどう影響したか考えてほしい
• このスタイルが合ったか否か、それはなぜか、著者に教えてほしい

英語

• move on

  • どんどん進む

• respectable

  • りっぱな

• canary in a coal mine

  • 警告、予兆

    • 炭鉱でカナリアを飼って、有毒ガスを検知したことから

• back-of-the-envelope calculation

  • (封筒の裏に走り書きするような)大雑把な計算