リーダブルコード要点まとめ

リーダブルコードの要点をまとめました。

名前に情報を詰め込む

• 明確な単語を選ぶ。
  • 例えば、Getではなく、状況に応じてFetchやDownloadなどを使う。
• tmpやretvalなどの汎用的な名前を避ける。
  • ただし、明確な理由があれば話は別だ。
• 具体的な名前を使って、物事を詳細に説明する。
  • ServerCanStart()よりもCanListenOnPort()の方が明確だ。
• 変数名に大切な情報を追加する。
  • ミリ秒を表す変数名には、後ろに_msをつける。これからエスケープが必要な変数名には、前にraw_をつける。
• スコープの大きな変数には長い名前をつける。
  • スコープが数画面に及ぶ変数に1-2文字の短い暗号めいた名前をつけてはいけない。短い名前はスコープが数行の変数につけるべきだ。
• 大文字やアンダースコアなどに意味を含める。
  • 例えば、クラスのメンバ変数にアンダースコアをつけて、ローカル変数と区別する。
• 誤解されない名前をつける。
  • filter, length, limitのように曖昧な意味の単語を避ける。
  • 上限の限界値を決めるときはmaxやminを、包含的範囲であればfirstやlastを、包含/排他的範囲であればbeginやendを、ブール値にはisやhasなどを使う。
  • disable_sslのような否定系は避ける。
  • 単語に対するユーザの期待にも注意する。例えば、get()やsize()には軽量なメソッドが期待される。

美しさ

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

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

• コメントすべきでは「ない」こと
  • コードからすぐに抽出できること。
  • ひどいコード（例えば、ひどい名前の関数）を補う「補助的なコメント」。コメントを書くのではなくコードを修正する。
• 記録すべき自分の考え
  • なぜコードが他のやり方ではなくこうなっているのか。（「監督コメンタリー」）
  • コードの欠陥を TODO: や XXX: などの記法を使って示す。
  • 定数の値にまつわる「背景」。
• 読み手の立場になって考える
  • コードを読んだ人が「えっ？」と思うところを予想してコメントをつける。
  • 平均的な読み手が驚くような動作は文書化しておく。
  • ファイルやクラスには「全体像」のコメントを書く。
  • 読み手が細部にとらわれないように、コードブロックにコメントをつけて概要をまとめる。

コメントは正確で簡潔に

• 複数のものを指す可能性がある「それ」や「これ」などの代名詞を避ける。
• 関数の動作はできるだけ正確に説明する。
• コメントに含める入出力の実例を慎重に選ぶ。
• コードの意図は、詳細レベルではなく、高レベル（業務レベル）で記述する。
• よくわからない引数にはインラインコメントを使う。（例：Function(/* arg = */ …)）
• 多くの意味が詰め込まれた言葉や表現を使って、コメントを簡潔に保つ。

制御フローを読みやすくする

• 比較（while ( a > b )）を書くときは、変化する値を左に、より安定した値を右に配置する。
• if / else文のブロックは適切に並び替える。一般的には、肯定形・単純・目立つものを先に処理する。
• 三項演算子・do/whileループ・gotoなどのプログラミング構成要素を使うと、コードが読みにくくなるため慎重に使う。
• ネストが多いと読みづらくなるため、ガード節などを使って直線的なコードを書くと良い。

巨大な式を分割する

• 説明変数を導入する。
  • 巨大な式を分割できる。
  • 簡潔な名前で式を説明することで、コードを文書化できる。
  • コードの主要な「概念」を読み手が認識しやすくなる。
• ド・モルガンの法則を使って、論理式をきれいに書き直す。
• 複雑な論理条件等がある場合は、問題を「否定」することで簡単に条件を組み立てられることもある。

変数と読みやすさ

• 邪魔な変数を削除する。
  • 中間結果の変数を使わないようにする。
• 変数のスコープをできるだけ小さくする。
  • 変数を数行のコードからしか見えない位置に移動する。
• 一度だけ書き込む変数を使う。
  • 変数に一度だけ値を設定すれば（あるいは、constやfinalなどのイミュータブルにする方法を使えば）、コードが理解しやすくなる。

無関係の下位問題を抽出する

• プロジェクトの固有のコードから汎用コードを分離する。
• 一般的な問題を解決するライブラリやヘルパー関数を作っていけば、プログラムに固有の小さな核だけが残る。
• 汎用コードを分離すると、境界線の明確な小さな問題に集中できるようになる。また、コードの再利用というメリットにもつながる。

一度に１つのことを

• 読みにくいコードがあれば、そこで行われているタスクを列挙し、別の関数（やクラス）に分割できるタスクを見つける。
• A1B1C1→A2B2C2→A3B3C3 ではなく、A1A2A3→B1B2B3→C1C2C3 のようにコードを書く。

コードに思いを込める

• プログラムを簡単な言葉で説明することで、コードがより自然になる。
• 説明で使っている単語やフレーズをよく見れば、分割する下位問題がどこにあるかが分かる。
• プログラムを言葉にすることで、バグが見つかったり、自分が見落としている部分や理解できていない部分を見つけたりすることができる。

短いコードを書く

• 不必要な機能をプロダクトから削除する。過剰な機能は持たせない。
• 最も簡単に問題を解決できるような要求を考える。
• 定期的に全てのAPIを読んで、標準ライブラリに慣れ親しんでおく。

テストと読みやすさ

• テストのトップレベルはできるだけ簡潔にする。入出力のテストはコード1行で記述できるといい。
• テストが失敗したらバグの発見や修正がしやすいようなエラーメッセージを表示する。
• テストに有効な最も単純な入力値を使う。
• テスト関数に説明的な名前をつけて、何をテストしているかを明らかにする。