A Philosophy of Software Designを読んだので忘備録としてまとめていきます。
A Philosophy of Software Design
- 作者:Ousterhout, John
- 発売日: 2018/04/06
- メディア: ペーパーバック
- 13章 Comments should describe things that aren't obvious from the code
- 14章 Choosing Name
- 15章 Write the comments first
13章 Comments should describe things that aren't obvious from the code
コードを書いた開発者がコードで表現できない情報を表すためにコメントを書く
暗黙的なルールや、なぜこの方法をとったのか？なぜこのコードが必要なのか？を表現する
詳細な実装を抽象化した情報を表現する
開発者が簡単に理解できてコードを修正できる状態や利用する側がコードを読まずに仕様を理解できる状態を目指す
コメントの分類
クラスやメソッドのインターフェースを説明するコメント
変数やクラスフィールドを説明するコメント
メソッドの内部処理を説明するコメント
依存性(修正範囲)を説明するコメント
コードに出てくる単語をかいつまんだような、コードを繰り返すコメントを書かない
コメントが多くなりすぎてコードが貧弱になっているならリファクタリングをする。
副作用や修正影響範囲など知っておいてもらいたい情報をコメントとして残す。
実装の詳細を表現する場合、コードがどう動くかではなく、何をしているかを理解しやすくなるようにコメントを書く。
読み手がわかりづらいと感じたコードは、開発者もわかりづらくなるものなので、コメントやコードを修正する
14章 Choosing Name
変数名やメソッド名、クラス名などをわかりやすくすることで、読み手の誤解を減らすことができる。
読み手が誤解しない名前か考える
汎用的に使われている単語だけを用いた名前はなくす。
名前がつけづらいものがあった場合、設計を疑う。
ある目的にそった名前をつける。
複数の目的をもった変数を作らない。
iが外のループ、jが中のループなどコードの慣習に沿った名前をつける。
コードの読みやすさは書き手ではなく読み手が判断する。
定義場所と実際に利用する場所が離れれば離れるほど定義する名前は長くすべき
15章 Write the comments first
コメントを最初に書く
コメントを書くことを後回しにすると、書くべきコメントの量が増えてしまったり、何を書いたらいいか思い出せず、全く書かないということになりがち
コードが書き終わっているとコメントも書き終わっている状態が理想
コメントを書くためにはクラスやメソッドの抽象的な要素を理解する必要があるため、設計の悪いところを見つけることができる。
クラスやメソッドや変数のコメントをシンプルに書けない場合、そもそもの設計に問題がある。
後からまとめて書くことに比べて、コメントを書くことが楽しくなる
コメントを先に書くことで結果として開発作業が早くなる
