はじめに
この記事は、私が今後リーダブルコードの復習し易くするための、
概要をまとめた手引書です。
要諦
コードは読みやすくなければいけない。
具体的には、他の人が自分のコードを読んで、理解する時間を最短にすること。
1章 理解しやすいコード
他の人が最短時間で理解できるようにする。
重要なのは、コードの長さが短いことではなく、他の人が読んで理解するのにかかる時間が短いこと。
そのためには、コメントがあることによりコードが長くなってしまっても、理解しやすくなるならば必要なこと。
2章 名前に情報を詰め込む
名前を見ただけで、情報が読み取れるようにする。
明確な単語を選ぶ
一見すると問題なさそうな単語でも、類語辞典で、もっと具体的で、限定的な単語があるかを調べる。
凡用的な名前は避ける
hogeやfooのような名前をつけるのは、名前のことを考えていない。
名前に情報を追加する
知らせなければいけない情報などがあったら、追加する。
例えば、ミリ秒を表す場合は、後ろに_msをつける。
名前のフォーマットで情報を伝える
クラスはキャメルケース、アンダースコアで始まるとローカル変数、などと名前のフォーマットによって区別する。
3章 誤解されない名前
他の意味と勘違いされないかを考える。
限界値を含めるときはminとmaxを使う
limitだけでは、最大なのか、最小なのかがわからない。
最小の場合は、min_limit
最大の場合は、max_limit
範囲を指定するときはfirstとlastを使う
rangeだけでは、どこからなのか、どこまでなのかがわからない。
ここからの場合は、first_range
ここまでの場合は、last_range
複数の名前を検討する
考えうる複数の名前を比較して、最も適切な名前を選ぶ。
4章 美しさ
読み手に優しい、一貫性のあるレイアウトにする。
一貫性のあるコードに整列する
余白、配置、順序に気をつけて、それぞれのコードを同じように整列させる。
5章 コメントすべきことを知る
コメントの目的は、書き手の意図を読み手に知らせること。
コメントするべきでは「ない」こと
コードからすぐにわかることをコメントに書かない。
自分の考えを記録する
なぜこのようなコードになったのかなどの意図を書く。
コードの欠陥にコメントをつける
改善が必要なコードに対して、#問題があるやあとで改善するなどの、これからコードをどうしたいかについてのコメントをつける。
定数にコメントをつける
その定数の値にした意図を知らせるため。
質問されそうなことを想像する
他の人は、コードを書いた当人ほどコードの意図を理解していない。
なので、読み手の立場になって質問されそうなところがないかを考える。
ハマりそうな罠を告知する
関数やクラスを文書化するときには、「このコードを見てびっくりすることは何か？どんなふうに間違えて使う可能性があるか？」を自分に問いかける。
コードを使うときに直面する問題を前もって予測しておく。
新しくチームに参加した人に対してコメントをつける
新しくチームに参加した人に、コードのことを教えることを仮定する。
その場合に、教えるようなことをコメントに書くべき。
要約コメント
長くて、一見では把握しきれない関数などに、どのような働きをする関数なのか説明を書く。
6章 コメントは正確で簡潔に
コメントは領域に対する情報の比率が高くなければならない。
コメントは冗長にならないように、簡潔にまとめる。
あいまいな代名詞を避ける
「これ」や「それ」などのあいまいな代名詞を使わずに、指す対象を明確に書く。
情報密度の高い言葉を使う
平易な言葉で長く書くよりも、一言で意味が取れる言葉を選んで短くまとめる。
7章 制御フローを読みやすくする
コードの読み手が立ち止まったり読み返したりしないように書く。
条件式の引数の並び順
if length >= 10
if 10 <= length
上のコードの方が良い。
左辺に調査対象(変化する値)をおく。
三項演算子
三項演算子を使えば、コードは短くなるが、読みにくくなる場合もる。
なので基本的には、if/else文を使い、簡潔になる場合に三項演算子を使う。
コードを短くするのではなく、他の人が理解するのにかかる時間を短くする。
8章 巨大な式を分割する
説明変数
式を簡単に分割するには、式を変数に代入して使う。
この変数を説明変数という。
if line.split('|')[0].strip() == "root":
説明変数を使うと、以下になる。
username = line.split('|')[0].strip()
if username == "root":
9章 変数と読みやすさ
コードが読みやすくならない変数は削除する
以下の条件に当てはまる変数は、本当に必要か考える。
* 複雑な式を分割できていない。
* 変数にを使うことによって、より明確にできていない。
* 一度しか使っていないので、重複コードの削除になっていない。
変数のスコープを縮める
スコープが広いと、把握すべき情報が広がってしまう。
なので、読みやすくするために範囲を狭める。