读书笔记-リーダブルコード

《リーダブルコード》读书笔记
The Art of Readable Code

1 理解しやすいコード

読みやすさの基本定理：コードは他人が最短時間で理解できるように書かなければいけない。

2 名前に情報を詰め込む

明確な単語を選ぶ

• 気取った言い回しよりも明確で正確な方がいい

汎用的な名前を避ける

• tmp/retvalなど空虚な名前
• あるいは、使う状況を選ぶ
• ループイテレータ：i/j/k/iterなどより、もっと明確な説明的な名前のほうがよい(e.g. users_i, members_i)

抽象的な名前よりも具体的な名前を使う

名前に情報を追加する

• 名前は短いコメントのようなものだ
• 追加する情報例：フォーマット、単位、危険や注意喚起する情報など

名前の長さを決める

• スコープが小さなければ短い名前でもいい
• 長い名前を入力するのは問題じゃない
• 頭文字と省略形(新しいチームメイトはその名前の意味を理解できるだろうか？)
• 不要な単語を投げ捨てる

名前のフォーマットで情報を伝える

• CamelCase、lower_separated、CONSTANT_NAMEなど

3 誤解されない名前

名前が「他の意味と間違えられることはないだろうか？」と何度も自問自答する

範囲について

• 限界値を含めるときは min/max を使う
• 範囲を指定するときは first/last を使う [first, last]
• 包含／排他的範囲には begin/end を使う [begin, end)

ブール値の変数名は頭に is/has/can/should などをつけてわかりやすくする

4 美しさ

一貫性と意味のあるやり方でコードを整形する

• 複数のコードブロックで同じようなことをしていたら、シルエットも同じようなものにする
• コードの「列」を整列すれば、概要が把握しやすくなる
• ある場所でA/B/Cのように並んでいたものを、他の場所でB/C/Aのように並べではいけない。意味のある順番を選んで、常にその順番を守る
• 空行を使って大きなブロックを論理的な「段落」に分ける

5 コメントすべきことを知る

コメントの目的は、書き手の意図を読み手に知らせることである。

コメントするべきでは「ない」こと

• コードからすぐにわかること
• ひどいコードを補う「補助的なコメント」。コメントを書くのではなくコードを修正すべき（優れたコード>ひどいコード+優れたコメント）

記録すべき自分の考え

• なぜコードが他のやり方ではなくこうなっているのか
• コードの欠陥をTODO:などの記法を使って示す
• 定数の値にまつわる「背景」

読み手の立場になって考える

• コードを読んだ人が「えっ？」と思うところを予想してコメントを付ける
• ハマりそうな罠を告知する、平均的な読み手が驚くような動作は文書化しておく
• ファイルやクラスには「全体像」のコメントを書く
• 要約コメント。読み手が細部に捕まられないように、コードブロックにコメントをつけて概要をまとめる