リーダブルコード 備忘録

はじめに

本記事は書籍『リーダブルコード』の内容の忘れた時にそなえて、要点を書きとめておくためのメモ（備忘録）です。

1. 読みやすさの基本原則

「理解までにかかる時間が短いコード」が、読みやすいコード
短さ＝読みやすさではありません。短くても意図が伝わらないコードは理解するコストが高くなる

2. 名前の付け方

2.1 情報を詰め込む

• 明確な単語を選ぶ
  • case1
    • NG: GetPage(url) → どこから取得するのか不明
    • OK: FetchPage, DownloadPage
  • case2
    • NG: Size → 何のサイズか分からない
    • OK: Height, MemoryBytes
  • case3
    • NG: Stop → 再開可能？完全終了？
    • OK: Pause（再開可能）, Kill（再開不可）

2.2 汎用的すぎる名前は避ける

• tmp や retval などは広いスコープでは避ける
• 狭いスコープや一時変数なら許容
• 多重ループでは i, j ではなく clubIndex, memberIndex のように説明的にする

2.3 名前に追加情報を持たせる

• 単位を含める: startMs, sizeBytes
• 注意喚起: plaintextPassword, unescapedComment

2.4 長さと省略

• スコープが狭ければ短くても良い
• 長い名前でも良いので説明的にする
• プロジェクト固有の略語は避ける。新規メンバーにはわからない
• 意味のない単語は削る

3. 誤解を避ける命名

• filter は動作が曖昧 → select（抽出）/ exclude（除外）
• 限界値は MIN_ / MAX_ を含める
• 範囲は first / last や begin / end を使う
• ブール値は is, has, can, should で始める（Rubyでは末尾?）
• get は軽量アクセスの期待 → 高コスト処理には別名を使う
• 候補を複数出し、比較して決定

4. 美しいレイアウトとフォーマット

• 改行は一貫性を持たせる
• 縦の線を揃える（変数の = や引数位置など）
• 並びによってコードの意味が変わらないのであれば、並び順に意味を持たせる（重要度順やアルファベット順）
• 宣言を論理的にグループ化し、理由をコメントで残す
• コードを空行で段落を分け、段落ごとに要約コメントを入れる

5. コメントの付け方

5.1 不要なコメント

• コードを見れば分かること
• 悪い命名を補足するコメント（→命名を改善する）

5.2 有用なコメント

• 思考過程の記録
• 不完全な実装（TODO, HACK）
• 定数の背景理由
• 想定される質問や落とし穴
• クラスや関数の概要（大きなスコープに有効）

5.3 コメントの質

• 正確かつ簡潔
• 関数に良い入出力例をコメントするのは万金に値するが、慎重に選択する
• コードの意図を高レベルで記述（NG: listを降順でソートする、OK: 値段の高い順番で表示する）

6. 複雑な式の整理

• 説明変数を導入する
  • 式の途中経過を説明変数として定義することで式を分割する
  • 説明文の役割を果たすことで可読性が上がるだけでなく、再利用することで重複をなくすことも可能
• ド・モルガンの法則を活用して否定条件を読みやすくする

7. 変数とスコープ

• スコープはできるだけ狭く
• 大きなクラスでは全てのメンバー変数を追跡するのが難しいので、大きなクラスは小さなクラスに分割する
• 書き込み回数を減らす（理想は一度だけ）

8. 無関係の下位問題を抽出

• 無関係の下位問題とはその処理がアプリケーションの本質的な目的とは直接関係なく、かつ自己完結していてどのアプリケーションから呼ばれるかを気にしなくて良い部分
• 無関係の下位問題を積極的に見つけて関数に抽出する
• プロジェクト特化でも可
• 小さな関数を用意しすぎると逆に読みにくくなるので注意

9. 関数の責務は1つ

• 複数タスクを列挙し、分割可能なら関数化
• 分割しない場合でも論理的段落で整理

10. 短く保つ

• 要求以上に作り込まない（過剰設計禁止）
  • 例
    • 要求：任意のユーザの経度、緯度に対して最も近い店舗を検索するように実装する
    • 前提：テキサス州の30店舗だけしか扱わない
    • 過剰設計：100%正しく実装するために日付変更線を跨いだ処理、北極や南極に近い時の処理なども真面目に実装する
• コードを短く保つ
  • 無関係の下位問題の抽出
  • 不要なコードは削除
  • プロジェクトをサブプロジェクトに分割する
• 再利用できるライブラリを活用
  • 車輪の再発明をしない
  • 身近なライブラリに親しみ、ライブラリを再利用できないかという観点を持つ

11. テストしやすいコード

• 入出力テストは一行で書けるように
  • テストの本質は「こういう状況と入力から、こういう振る舞いと出力を期待する」のレベルまで要約できる
  • これは一行でまとめられることが多い
• 失敗時に原因が分かるメッセージ
• 小さいクラス、単一責務、疎結合、シンプルな関数のように実装をシンプルにする

まとめ

読みやすいコードとは、意図がすぐに理解できるコードです。
命名、フォーマット、コメント、スコープ設計、関数分割、テスト設計など、
あらゆる要素が「理解のしやすさ」に直結します。