リーダブルコードまとめ｜「他人が読めるコード」が最強のコード


改めて、リーダブルコードを確認したので、備忘用にまとめます！

プログラムを書いているとき、私たちはどうしても

  • できるだけ短く書きたい
  • とりあえず動けばいい

と考えてしまいがちです。

しかし実際のプロダクト開発では、

コードを書く時間より、「読む時間」「メンテナンスする時間」のほうが圧倒的に長い

と言われています。
つまり、本当に価値があるのは

他の人（未来の自分も含む）が読んだときに、意味を理解するまでの時間が短く済むコード

です。これこそが「リーダブルコード（Readable Code）」の核となる考え方です。

✅ リーダブルコードとは何か

リーダブルコードの定義はとてもシンプルです。

読む人がすばやく理解できるコードが、良いコード

  • 単に短いコードよりも、「読みやすいコード」を優先する
  • 今の自分が書きやすいかではなく、未来の自分や他人が読みやすいかを重視する
  • 長期的には、読みやすいコードのほうがバグが少なく、変更や拡張も容易で、結果としてコストが下がる

📚 リーダブルコードの主要な教え：整理

ここからは、リーダブルコードのエッセンスをもう少し整理していきます。

🔧 表面的な改善（命名・フォーマット・コメントなど）

1. 名前（変数・関数・クラス）は「何をする／何を表すか」が明確に伝わるように

  • get_page のような抽象的な名前よりも、download_page, fetch_page_from_cache のように「どこから何を取得するか」が分かる名前にする。
  • tmp, retval, data のような汎用・曖昧な名前は避け、可能な限り意味を持つ名前にする。
  • スコープの広い変数（グローバルやクラスフィールドなど）ほど、具体的で説明的な名前をつける。
    逆に、短いスコープ内だけで完結する変数なら、多少短くてもよい。

2. 命名は誤解・あいまいさを生まないように

  • 境界値・条件式の名前には min, max, first, last, begin, end などを使い、
    その値が「範囲のどこなのか（含む／含まない）」まで含めて分かるようにする。
  • 真偽値を返す変数・関数には is_..., has_..., can_... などの接頭辞を用いると、
    それが「条件・状態」を表していることが一目で分かる。
# 良い例
is_expired = token_expiry < now
has_permission = user_role in allowed_roles
can_retry = retry_count < MAX_RETRY

3. コードの書式／レイアウトにも気を配る

  • インデント、改行、空白、括弧の位置などは常に一貫させる。
  • 視覚的に読みやすく、コードの構造が一目で把握できる見た目を作る。
  • ただし、「美しさ」だけを追い求めて意味を詰め込みすぎると本末転倒。
    見た目と可読性のバランスが大事。
# ❌ 悪い例
if(x>0): print("ok")
else:print("ng")

# ✅ 良い例
if x > 0:
    print("ok")
else:
    print("ng")

4. コメントの使い方を慎重に

  • コメントは過剰に入れるべきではない。
  • 本質的には「必要なときだけ、かつ正確で簡潔に」書く。
  • コードの動きを逐一説明するコメントはむしろノイズになることが多い。
# ❌ Bad: 単にコードを日本語にしただけ
i = i + 1  # iに1を足す

# ✅ Good: なぜこの処理が必要なのかを書く
# API負荷を抑えるためにポーリング間隔を2倍に延ばす
polling_interval *= 2
  • コメントが必要になるほど複雑なロジックがあるなら、
    まずはそのコードをリファクタリングし、「読んでわかる構造」にすることを検討する。

🧩 コード構造と処理の分割 — ロジックを整理する

1. 「一度に一つのこと」をコードにさせる

  • 1つの関数／メソッド／コードブロックが複数の目的・処理を持たないようにする。
  • 1つのタスクに集中させることで、理解しやすく、保守やテストも簡単になる。
# ❌ 悪い例：いろいろ詰め込みすぎ
def process_user(user):
    validate(user)
    save_user(user)
    send_welcome_mail(user)
    log_to_slack(user)

# ✅ 良い例：責務ごとに分割
def process_user(user):
    validate_user(user)
    persist_user(user)
    notify_user_created(user)
  • 必要なら複数の処理に分割して、別の関数・モジュールに切り出す。

2. 無関係な下位問題（副次的な処理）は抽出して分離する

  • 関数やクラスを見たときに、まず「このコードの高レベルな目的は何か？」を自問する。
  • その目的に直接関係しない処理が混ざっているなら、別の関数へ切り出す。
  • 汎用的に使える処理はユーティリティやヘルパーとして抽象化し、
    プロジェクト固有の部分と切り分ける。

3. 複雑・巨大な式や処理チェーンは分割して、ひと目で追いやすくする

  • 長い式、深いネスト、複数の変換・判定を1行で書く…といったスタイルは避ける。
  • 途中で処理結果を変数に受け、ステップごとに書く。
# ❌ 悪い例：一行に詰め込んでいる
result = sum(map(lambda x: x**2, filter(lambda x: x > 0, numbers)))

# ✅ 良い例：ステップを分割
positive_numbers = [n for n in numbers if n > 0]
squared_numbers = [n**2 for n in positive_numbers]
result = sum(squared_numbers)
  • こうすることで、読む人の脳の負荷（頭の中の「思考スタック」）を軽くできる。

🧠 なぜこの考え方が重要か — 保守性とチーム開発の観点

  • 一度書いたコードは、時間が経てば自分でも何をやっているか忘れる。
  • さらに、他のメンバーや将来入ってくる人もそのコードを読むことになる。
  • だからこそ、「今だけ読みやすさを犠牲にして早く書く」のではなく、
    未来の保守性と可読性を優先するべき。

可読性の高いコードは：

  • バグが見つけやすい
  • レビューがしやすい
  • 仕様変更や拡張にも耐えやすい

結果として、長期的なコスト削減につながる。

📝 「リーダブルコードのためのコーディング規約」案（user rules 向け）

ここからは、チームのコーディングルールやCursor / Editor の「user rules」にそのまま貼れる形で整えた文言です。

読みやすいコードを書くための基本ルール

  1. コードは読む人のために書く。
    コードを書くときは、未来の自分や他人が「読んだときにできるだけ早く理解できる」ことを最優先する。
    冗長な省略や過度な凝縮は避ける。
  2. 命名は意味を持たせ、あいまいさを避ける。
    • 変数名・関数名・クラス名には「何を／どこから取得するか」「何をするか」が明確にわかる語を用いる。
    • tmp, data, retval のような汎用・曖昧な名前は避け、可能な限り具体的かつ説明的な名前にする。
    • スコープが広い変数ほど詳細な名前をつけ、スコープが狭ければ短くてもよい。
    • 境界値や範囲、状態判定には min, max, first, last, begin, end, is_, has_, can_ などの接頭辞／接尾辞を活用する。
  3. コード構造と処理を分割し、一度に一つのタスクに集中させる。
    • 1つの関数／メソッド／クラスは、できるだけ「1つの責務（タスク）」に限定する。複数の責務があれば分割する。
    • 副次的・汎用的な処理はライブラリ／ユーティリティ／ヘルパーとして切り出す。
    • 複雑・大きな式やネストは避け、適切に途中変数やサブルーチンに分割して可読性を高める。
  4. コメントは最小限かつ意味あるときだけ書く。
    • 必要以上に冗長なコメントでロジックを説明するのは避け、可能であればコードの構造そのものを改善する。
    • コメントが必要な場合には、「なぜその処理が必要か」「前提や副作用」を簡潔に記述する。
  5. コードのフォーマット・レイアウトは一貫性を保つ。
    • インデント、改行、空白、括弧配置などをチームで統一し、ひと目で構造が把握できるようにする。
    • ただし「見た目の美しさ」を優先するあまり、意味が曖昧／詰め込みすぎになるのは避ける。
  6. 常に「読む時間」＝「将来的なメンテナンス時間」を意識する。
    • 今は短く書くために凝縮しても、将来的にコードを読むのがつらくなっては意味がない。
    • 保守性と拡張性を重視して、読みやすく、構造が追いやすいコードを書く。

✅ 注意点

  • これらのルールは「絶対」ではなく、チームやプロジェクトの文脈や規模に応じて柔軟に運用する。
  • シンプルなスクリプトや一時的なスニペットでは、すべてを厳密に守ると過剰になることもある。
  • ただし、チーム開発や長期運用されるコードベースでは特に重要であり、
    これらの原則を守ることで、後々のコストを大きく下げられる。

💡 簡単な Before / After 例

# Before: 意図が読み取りづらい例
def calc(a, b, c):
    tmp = a * b
    if c:
        return tmp + 1
    else:
        return tmp - 1

# After: リーダブルコードを意識した例
def calculate_score(base_value: int, weight: int, is_bonus: bool) -> int:
    """
    スコア計算：
    - is_bonus が True のときは +1
    - False のときは -1
    """
    raw_score = base_value * weight
    return raw_score + 1 if is_bonus else raw_score - 1
  • 関数名から「何を計算しているのか」が分かる
  • 引数名から用途が分かる
  • is_bonus によって条件の意味が明確
  • コメントは「なぜそういうルールか」「仕様の要約」に絞られている

🔗 参考文献・引用元

タイトルとURLをコピーしました