A Philosophy of Software Designの13章要約
本内容は「A Philosophy of Software Design」の13章を要約する記事です。
過去記事
- A Philosophy of Software Designの3章要約 - なになれ
- A Philosophy of Software Designの5章要約 - なになれ
- A Philosophy of Software Designの7章要約 - なになれ
- A Philosophy of Software Designの9章要約 - なになれ
- A Philosophy of Software Designの11章要約 - なになれ
12章の紹介
他担当の方が要約した12章の内容を引用します。
- 12章 なぜコメントなのか？4つの理由
- コメントを書かない理由
- 良いコードはセルフ・ドキュメント化される
- コメントを書いている暇はない
- コメントは古くなり、誤解を招くようになる
- 私が見たコメントはすべて価値がない。なぜ悩むのか？
- 良いコメントを書くことは、ソフトウェア全体の品質を大きく変えることができる
- コメントはコードの価値を高め、抽象化の定義やシステムの複雑性を管理する上で基本的な役割を果たす
- コメントがなければ、複雑さを隠すことはできない
- コメントを避ける言い訳とそれに対する反論
- "良いコードはセルフ・ドキュメント化される"
- コードで表現できない設計情報はかなりの量にのぼります。例えば、クラスのインターフェースのうち、メソッドのシグネチャなど、コードで正式に指定できるのはごく一部だけ
- 大規模なシステムでは、ユーザーがコードを読んで動作を学ぶことは現実的ではない
- もしユーザーがメソッドを使用するためにコードを読まなければならないのなら、それは抽象化ではありません。コメントがない場合、メソッドの抽象化は宣言だけとなり、宣言にはメソッドの名前、引数や結果の名前と型が指定されます。この宣言は、それ自体で有用な抽象化を提供するには、あまりにも多くの重要な情報が欠けています
- コメントによって、呼び出し側が必要とする追加情報を取得することで、実装の詳細を隠蔽しつつ、簡略化された表示を完成させることができる
- 抽象化を使って複雑さを隠したいのであれば、コメントは不可欠
- コメントを書いている暇はない
- 良いコメントはソフトウェアの保守性に大きな違いをもたらすので、そのために費やした努力はすぐに報われる
- 良いドキュメントを作ることの利点は、このコストをすぐに相殺することができる
- ドキュメントを書くという行為は、設計全体を改善する重要な設計ツールとして機能する
- コメントは古くなり、誤解を招くようになる
- ドキュメントを最新の状態に保つには、それほど大きな労力は必要ありません
- 第16章で説明する
- 私が見たコメントはすべて価値がない。なぜ悩むのか？
- しっかりとしたドキュメントを書くことは、一度方法を知ってしまえば、難しいことではありません
- コメントの背後にある全体的な考え方は、設計者の頭の中にありながらコードで表現することができなかった情報を捕捉すること
- ドキュメントがなければ、将来の開発者は、開発者のオリジナルの知識を再取得するか、推測しなければなりません
- ドキュメントは、開発者が変更を加えるために必要な情報を提供し、開発者が無関係な情報を無視しやすくすることで、認知的負荷を軽減することができます
- ドキュメンテーションは、システムの構造を明確にすることで、どのような変更にどのような情報やコードが関連するのかを明確にし、未知の未知数を減らすことができます
13章の要約
- 13章 コメントには、コードからではわからないことを書くべき
- 概要
- コメントの原則は、コードからではわからないことをコメントで記述すること
- 開発者は、外部から見える宣言以外のコードを読むことなく、モジュールが提供する抽象化を理解できるようにする必要がある
- 規約を選ぶ
- コードを繰り返さない
- やってはいけないコメント
- コメントの情報が、コメントの隣にあるコードからすでに明らかである場合、そのコメントは役に立ちません
- 下位レベルのコメントで正確さを増す
- コードと同じレベルのコメントの書き方について
- 変数宣言の名前と型だけでは説明不足なので、それを補うようにコメントを書く
- 例
- この変数の単位は何ですか？
- 境界条件は包括的か排他的か？
- null値が許される場合、それは何を意味するのか？
- 変数が最終的に解放または閉じなければならないリソースを参照している場合、誰がそのリソースを解放または閉じる責任がありますか?
- 「このリストには少なくとも一つのエントリーが含まれている」というような、その変数に対して常に真である特定の性質（不変量）はありますか？
- 変数がどのように操作されるかではなく、その変数が何を表しているかに注目する
- 高レベルのコメントで直感を高める
- メソッド内のコメントやインターフェイスのコメントについて
- コードの全体的な意図と構造を理解できるようにする
- 例
- このコードは何をしようとしているのか？
- このコードのすべてを説明できる最も簡単なことは何か？
- このコードで最も重要なことは何だろうか？
- 該当のコードが実行される理由を説明するのも良いコメント
- インターフェイスの文書化
- コメントの役割の一つは、抽象化されたものを定義すること
- 抽象化を文書化する最初のステップは、インターフェイスコメントと実装コメントを分けること
- インターフェイスコメントは、クラスやメソッドを使用するために誰かが知っておく必要がある情報を提供し、抽象化を定義する
- もし、インターフェイスのコメントが実装についても記述しなければならないのであれば、そのクラスやメソッドは浅いということになる
- 実装のコメントは、クラスやメソッドが抽象化を実装するために内部でどのように動作するかを記述する
- クラスのインターフェイスコメントについて
- 実装の詳細や特定のメソッドの詳細を記述することなく、クラスの全体的な機能を記述する
- このクラスの各インスタンスが何を表しているかも記述する
- このコメントではクラスの制限事項 (複数のスレッドからの同時アクセスはサポートしない) を説明する
- メソッドのインターフェイスコメントについて
- レッドフラグ
- メソッドのインターフェイスのコメントがメソッドを使用するために必要でない実装の詳細を記述している場合はレッドフラグである
- インターフェイスコメントに対する誤り
- 実装のドキュメントは有用だが、それはメソッドの中に書くべきで、インターフェイスのドキュメントとは明確に区別する
- 実装コメント：何を、なぜ、どのようにではなく
- メソッドが内部でどのように動作するかを読者が理解するのを助けるためにメソッドの内部に表示されるコメント
- ほとんどのメソッドは短くてシンプルなので、実装コメントは必要ありません
- 実装コメントの主な目的は、コードが何をしているかを読者が理解するのを助けること
- 長いメソッドには、メソッド全体のタスクの一部として異なることを行ういくつかのコードブロックがあります。各ブロックの前にコメントを追加し、そのブロックが何を行うのかについて高レベル (より抽象的) の説明を提供する
- ループの場合、ループの前にコメントを記述し、各ループで何が起こるかを説明すると良い
- バグフィックスで目的がはっきりしないコードを追加する必要がある場合、なぜそのコードが必要なのかを説明するコメントを追加する
- 問題点についてきちんと書かれたバグレポートがある場合のバグフィックスでは、 その詳細をすべて繰り返すのではなく、バグ追跡データベースの問題を参照するコメントを記述する
- クロスモジュール設計の決定
- クロスモジュールの決定は複雑で微妙なことが多く、多くのバグの原因となっているため、クロスモジュールのための優れたドキュメントが重要
- クロスモジュールのドキュメントの課題は、開発者が発見できるような場所にドキュメントを配置すること
- designNotesというファイルを作り、まとめて記録する方法がある
- コメントにはdesignNotesを参照する旨を書く
- 最新の状態を維持するのが難しいという欠点はある
- 結論
- コメントの目的は、システムの構造と動作が読者にとって明らかであることを保証すること
- コードから容易に推測できない情報が大量にあります。この情報を補うのがコメントである
- コードレビュー時にコードが明確ではないとされた場合、彼らが何を分かりにくいと思ったのかを理解し、より良いコメントやより良いコードでそれを明確にできるかどうか試してみましょう
感想
- リーダブルコードで見たような既視感があるが、実践できていない
- ここに書かれている内容を全てやろうとするとコストが高い、インターフェイスコメントを記述することから始めたい
