読みやすいコードは、読みやすい文章である

「読みやすさ」に悩んでいませんか？
結論：読みやすいコードは「意図が伝わる文章」と同じ
文章に例えるとよく分かる「読みやすさ」の正体
まとめ：コードも文章も「伝わること」がゴール

「読みやすさ」に悩んでいませんか？

コードを書いていると、ふと立ち止まって思うことがある。「このコード、半年後の自分が読んで理解できるだろうか？」あるいは、「チームメンバーがこれをレビューするとき、イライラしないだろうか？」
エンジニアなら誰もが一度は感じる悩みだ。特に、レビューで「もっと読みやすくして」と言われても、具体的に何を直せばいいのか分からず、心が折れそうになることもあるだろう。

この記事では、コードの読みやすさを“文章”に例えて考えることで、直感的に理解できる方法を紹介する。文章が読みやすいと感じるときのポイントをコードに置き換えることで、コードレビューが怖くなくなるし、メンタルを削らずに改善できるはずだ。

結論：読みやすいコードは「意図が伝わる文章」と同じ

結論から言うと、読みやすいコードとは、読み手が迷わず意図を理解できるコードである。
そしてそれは、良い文章と同じ条件を満たしている。

一文一意：一つの文に一つの意味 → 一つの関数に一つの責務
適切な段落分け：話題ごとに段落を分ける → 処理を関数やクラスに分割する
無駄な言葉を省く：同じ表現を繰り返さない → 重複コードをなくす（DRY原則）
論理が自然につながる：接続詞が明確 → コードの処理フローが追いやすい

要するに、「コードを文章のように読みやすくする」ことが、可読性を高める最短ルートなのだ。

文章に例えるとよく分かる「読みやすさ」の正体

1. 意味が明確であること

文章では主語と述語が明確だと読みやすい。同じように、コードでは変数名・関数名が明確だと理解しやすい。

// 悪い例
$data = getData();
process($data);

// 良い例
$userList = fetchActiveUsers();
sendWelcomeEmail($userList);

変数名と関数名を見ただけで「何をしているか」が分かる。文章で言えば、「私はリンゴを食べた」とストレートに書くのと同じだ。

2. 構造が整理されていること

長文をそのまま書き連ねると読みづらい。コードも同じで、長い関数は読む気を削ぐ。

// 悪い例：一つの関数が長すぎる
function processOrder($orderId) {
    // 受注データ取得
    // 在庫チェック
    // 支払処理
    // 出荷処理
    // 通知メール送信
}

// 良い例：処理を分割する
function processOrder($orderId) {
    $order = fetchOrder($orderId);
    validateStock($order);
    processPayment($order);
    shipOrder($order);
    notifyCustomer($order);
}

小分けにした関数名が「見出し」の役割を果たし、処理の流れを追いやすくなる。

3. 冗長でないこと

文章で同じことを何度も繰り返すとくどい。同じ処理をコピペするのも同じくらいくどい。

// 悪い例
$user = $db->query("SELECT * FROM users WHERE id = 1")->fetch();
echo htmlspecialchars($user['name']);

$product = $db->query("SELECT * FROM products WHERE id = 5")->fetch();
echo htmlspecialchars($product['name']);

// 良い例：DRYに書く
function fetchById($table, $id) {
    global $db;
    return $db->query("SELECT * FROM {$table} WHERE id = {$id}")->fetch();
}

function e($str) {
    return htmlspecialchars($str, ENT_QUOTES, 'UTF-8');
}

$user = fetchById('users', 1);
$product = fetchById('products', 5);
echo e($user['name']);
echo e($product['name']);

変更があったとき、共通関数を直せば全体に反映される。文章で言えば、「同じ話を何度も書く代わりに見出しや注釈でまとめる」感覚に近い。

4. 流れが自然であること

読みやすい文章は前後の論理が自然につながっている。コードも、処理の順序が直感的であると読みやすい。

例えば条件分岐では、先にエラーケースを弾いてから正常系を書くとスッキリする。

// 悪い例：ネストが深い
if ($user) {
    if ($user->isActive()) {
        process($user);
    }
}

// 良い例：早期リターン
if (!$user) return;
if (!$user->isActive()) return;

process($user);

深いif文の入れ子は、文章で言えば「カッコだらけの長文」で、頭がこんがらがる原因だ。

5. 読み手を意識していること

文章を書くときに読み手の知識レベルを考えるように、コードでもチームの平均スキルに合わせるべきだ。

抽象化しすぎると「一見かっこいいが、何をしているか分からないコード」になり、チーム全体の生産性が下がる。読みやすさはチーム全員で共有できる基準に落とし込む必要がある。

文章	コード
難しい専門用語を多用する	高度なデザインパターンを多用する
文脈が飛んで読者が迷子になる	依存関係が複雑で追えない
段落がなく詰め込みすぎ	長大な関数・巨大クラス