A Philosophy of Software Design ch12 Why Write Comments? -- The Four Excuses

APoSDソフトウェア設計勉強メモ

出典: 


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 に反する
    • 大きなシステムでは非現実的
  • 利用者がメソッドの実装を読まなければならないということは、抽象化できていないということ

    • 抽象とは、ある実体から、必要な情報を保ちつつ、不必要な詳細を省いたもの
    • コメント無しでシグネチャだけでは必要な情報を表現しきれない
    • 例: startend引数をとるメソッド

      • [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

  • 設計思想のうち、コードで表現できない情報をコメントに込める

    • 低水準の詳細

      • 例: 癖のあるハードウェアのためにトリッキーなコードが必要になった
    • 高水準の概念

      • 例: クラスの理論的根拠
  • 【補】きのこ56: 未来へのメッセージ

    • 将来、他の開発者が参入し、コードに変更を加えることになる

      • 数週間後の自分かもしれない
    • コメントがあると

      • 素早く
      • 正確に仕事にかかれる
    • コメントがないと

      • 前任者の意図を汲み取るのに時間がかかり
      • 誤解によるバグ埋め込みのリスクもある
  • 複雑性の減少

    • 複雑性の3つの柱(再掲)

      • 変更の増幅
      • 認知の負荷
      • わからないことがわからない
    • よいドキュメンテーションは、最後の2つを減らす

      • 認知の負荷

        • モジュールの変更に必要な情報を提供する
        • 関係のない情報を無視しやすくする

          • 【補】実装を覗きにいかなくてよい
      • わからないことがわからない

        • システムの構造を明確化する
        • ドキュメントとコードとの紐付けが明確になる
  • 複雑性の主要な原因の排除

    • 複雑性の原因(再掲)

      • 依存
      • 不明瞭
    • よいドキュメンテーションは、依存を明確化し、不明瞭さを排除する

英語

  • prevalence

    • 広く知られている
  • drudge

    • Verb: 骨の折れる仕事をこつこつ行う
    • Noun: こつこつ働く人
  • why bother

    • …する必要はない

      • 反語的
  • solid

    • 中身のある?

      • worthlessの対義語的に使われているので多分これ
  • quirk

    • くせ
  • debunk

    • 嘘であることをあばく