本記事執筆に至った背景と目的

最近『リーダブルコード』を流し読みした。
「名著だ」「必読だ」といった評価はよく耳にする。

とはいえ、実際に読んでみると、意外と拍子抜けしたのも正直な感想だった。悪く言えばTipsの寄せ集めに見えたのだ。

しかし、『リーダブルコード』冒頭では、こうしたTipsを貫く核心的な考え方が明言されている。

コードは他の人が最短時間で理解できるように書かなければいけない。
…(中略)…それから、「理解する」っていう言葉には、高いハードルを設けてある。「コードを理解する」というのは、変更を加えたりバグを見つけたりできるという意味だ。

『リーダブルコード』p.3より抜粋

本記事では、この核心をさらに深掘りするかたちで、「他者に何かを伝えるとはどういうことか？」という普遍的な問題に立ち戻ってみたい。

本記事は、『リーダブルコード』の要約やテクニック集ではない。あくまで、「コードで伝えるとは何か？」という問いに向き合いたい人に読んでもらえたら嬉しい。まずは本記事を読んでから『リーダブルコード』を読んでもらうと、強弱をつけて理解できるかと思う。

読みやすいコードとは

情報伝達における本質

読みやすいコード云々以前に、文字を書き、人に伝えるとはどういうことだろうか。

入試現代文の記述問題に解答をするとき、クライアント向けにレポートを書くとき、そしていつかの誰かが読解するかもしれないプログラムをコーディングするとき──。

相手に自分の考えを伝えるうえで、すべて根底にある考えは同じことである。なぜなら、

我々が伝達すべき情報を発信する
相手がこれを受け取り、理解する
相手が行動へ移す（例：採点、社内稟議、コード改修…など）

というプロセスは同一であるからだ。これらの情報伝達における本質は以下の通りである。

自分の伝えたいことが「相手に『低負荷で』『正しく』伝わるか？」、これを最大限に熟考することが本質である。

ここで私は

低負荷：理解までの時間的コストが少なく、精神的エネルギーの消費もないこと
正しい：情報伝達後に「自分の伝えたいこと」と「相手に伝わったこと」が一致している状態

と定義することにする。

もっともコードは将来の自分も読み返す点で、答案やレポートと異なる。しかしそれでも伝えることの本質は共通である。まずはこの本質を意識しながら、本記事や『リーダブルコード』を読んでほしい。

情報伝達プロセスの分解

さて情報伝達のプロセスを便宜上、

考える
書く

という2つのフェーズに分解したい。もちろん、実際にはこれらは明確に分離できず、書きながら考えを深めたり、書いたものを見直して思考を修正したりと、相互に行き来する複雑な活動である。

しかし、何を伝えるかを固める「考える」フェーズと、どう伝えるかを形にする「書く」フェーズを意識的に区別することは、伝達の質を高める上で非常に有効だと思う。
そしてこれは、我々が他者へ情報を伝達することにおいて、普遍的な営みであるはずだ。具体例を挙げつつ、各フェーズについて見ていこう。

1. 考える

まず自分が伝えたいことを正確に理解し、筋道立てて組みなおす（＝構造化する）必要がある。

たとえば、Git 初心者が rebase という操作について文章で説明せよと言われたらどうだろう。

「rebaseって結局何が起きるの？」
「ブランチの履歴を書き換えるって安全なの？」
「mergeとの違いは？」

疑問が尽きず、概念が整理できないうちは一行も書けない。知らないことは伝えられないのである。

一方で、例えば「カレーを作る方法を教えて」と言われたらどうだろう。自分が何度もカレーを作っていて、その手順や材料、注意点を理解し、頭の中で整理できていれば、次のように伝えられるはずだ。

玉ねぎ・人参・じゃがいも・肉を一口大に切る

鍋に油を熱し、肉を炒めてから野菜を加えて炒める

水を加えて煮込み、アクを取る

火を止めてルウを入れ、再び弱火でとろみが出るまで煮る

これは自分の理解を整理し、伝えられている好例だ。書く前には、意識的・無意識的問わず「考える」という準備段階が必要なのである。

流石にカレーは簡単すぎる例だが、ステップを明確にしなければ実行不可能であるという点において、複雑なコーディングにも通ずるものがある。

コーディングにおいて「考える」とは、例えば実装ロジックそのものだろう。login apiを作成するとき、どのように実装するのだろうか？最もシンプルには、以下のように構成される。

入力：email / password
処理：
- パスワードをハッシュ化する
- DB でユーザレコードと突き合わせる
出力：本人確認できれば認証情報を詰め込んだトークンを発行し返却

こうして構造を組む段階が 「考える」 であり、ここが曖昧なままでは、コードの可読性以前に、その実装自体が困難になる可能性さえある。「考える」ことは、知識をただ持っていることではなく、それを整理し、自分の外へ出力できるようにする下準備だと言える。

2. 書く

「考える」ことができたら、次は「書く」段階へ入る。「書く」ためには大きく分けて2つ力が必要である。

言語の知識を持っているか
伝わりやすい工夫ができるか

2-1. 言語の知識を持っているか

考えを整理できても、言語（自然言語、プログラミング言語問わず）の知識がなければ表現ができない。例えば「カレーの作り方を英語で説明してください」と言われたら、どうだろう。翻訳ツールが使用できない状況におかれた、英語の知識が全くない人には、カレーの作り方を伝えることは不可能である。もし知識があれば

Chop the onion, carrot, potato and meat into bite-size pieces.

Heat oil in a pot and sauté the meat, then add the vegetables.

Pour in water, skim off the scum, and simmer until tender.

Turn off the heat, add curry roux, and thicken over low heat.

と書ける。言語能力は表現の前提であり、自分の考えを自分の外の世界へアウトプットするには不可欠である。

コーディングだってそうだろう。Javaを知らないならば、Generative AIの手助け無しではJavaでの実装はできない。そしてここは「リーダブルコード」の守備範囲ではない。

リーダブルコードは「伝えるための工夫」において本領を発揮する。

2-2. 伝わりやすい工夫ができるか

情報伝達における本質とは「相手に『低負荷で』『正しく』伝わるか？」であると述べた。

どのような実装が「低負荷で」「正しく」伝えるのか？という観点で、以下に示すサンプルコードを確認する。言語はPythonである。この関数は与えられた数値リストから0より大きい値のみを抽出し、その平均を計算して返すものである。

優しいコード

def calculate_average_of_positive_numbers(numbers: list) -> float | None:
    if not numbers:
        print("処理対象の数値がありません。空のリストが渡されました。")
        return None

    positive_numbers = [num for num in numbers if num > 0]

    if not positive_numbers:
        print("処理対象の正の数がありません。リスト内に0より大きい数値が見つかりませんでした。")
        return None

    total = sum(positive_numbers)
    average = total / len(positive_numbers)

    print(f"正の数の合計: {total}")
    print(f"正の数の平均: {average}")

    return average

■ 一意に伝わる命名をする

正しく情報を伝達するために最優先で必要な手段が「命名」である。命名規則に関する言及はリーダブルコードにおいてもはじめの章で行われている重要なポイントでもある。

日本語で話すときは「玉ねぎ」をtなどと呼ぶひとは絶対にいない。なのに、プログラミングではそういった命名をする人間がいる。

まずは以下の悪い例を見てほしい。

悪い命名によるコード

def f(l):
    if not l:
        return None
    
    p = [n for n in l if n > 0]
    
    if not p:
        return None
    
    t = sum(p)
    a = t / len(p)

    return a

中身を見ればどんな実装かを理解することは容易だろう。しかしそれは実装内容が平易だからだ。現場レベルのもっともっと難解なコードだったら…？

丁寧な命名はソースコードの解読者の推論の手間を省き、認識のずれを予防することができる。正しい命名は情報を伝える上で非常に重要であると言える。

calculate_average_of_positive_numbers関数も「正の数の平均値を計算する関数である」ということが一目で伝わる。ほかにも、positive_numbersやtotalといった命名は、その変数がどのような意味を持つのかが一目でわかる。

# 0より大きい数値のみを抽出するリストであることが、命名からも一目で伝わる。
positive_numbers = [num for num in numbers if num > 0]

命名をする際には過不足なく本質情報を詰め込むことが必要だ。関数名・変数名は多少長くなっても伝わるほうが絶対に良い。個人差はあるだろうが、例えば関数名だってfよりもcalculate、calculateよりもcalculate_average、calculate_averageよりもcalculate_average_of_positive_numbersの方がわかりやすいと私は思う。

■ 解読者の記憶リソースを割かない

相手の記憶リソースを割かないことで、解読者にとって低負荷なソースコードになる。この観点においてcalculate_average_of_positive_numbers関数は2つの工夫が施されている。

早期リターンを実装している
「早期リターン」とは、条件分岐の中でreturnを使って関数を終了させることである。これによりロジックを追いかけることが容易になる。例えば、calculate_average_of_positive_numbers関数のif not numbersの条件分岐では、引数numbersが空リストであればreturn Noneを実行している。これにより、後続の処理を実行する必要がなくなる。
変数のスコープを最小限にする
変数が必要な期間を短くすることで、その変数の状態を追う必要がなくなる。或いは、他の場所での意図しない変更を防ぐこともできる。
calculate_average_of_positive_numbers関数においては、ローカルにpositive_numbers変数が定義されており、そのスコープは関数内に限定される。この関数を利用し終わったら不要になるので、もう記憶から追い出してしまって構わない。

余談として、後者について新人プログラマがよくやる実装が以下である。

新人プログラマがよくやる実装

flag = False
...
if flag:
    ...
    ...

flagという変数を定義し、ループを抜け出すかどうかを判定している。これは定義不要な変数で、一般的にはbreakやreturnを使用することで処理を代替することができる。
このような使われ方をするflag変数はスコープが大きくなることが往々にしてあり、複数個所でflag = True/Falseの書き換えが行われる可能性がある。その結果、flagの状態を追いかけることが困難になり、コードの可読性が低下することも避けれない。

■ レイアウトが美しいコード

レイアウトはコードの見た目を整えることで、コードの可読性を高めることができる。例えば、コードのインデントや空白の使い方、変数名の配置などを工夫することで、コードの構造が明確になり、読みやすくなる。

まとめ

本記事では、『リーダブルコード』が提示する数々のTipsの根底にある「他者に何かを伝えるとはどういうことか？」という普遍的な問いに立ち返り、その核心を深掘りした。

目指すべきは、常に「相手に『低負荷で』『正しく』伝わる」情報伝達である。

私たちはまず何を伝えるかを徹底的に「考える」必要がある。このフェーズでコードのロジックや構造が曖昧なままだと、その後の「書く」作業以前に、そもそもコードを組み立てることすら困難となる。

そしてその明確な思考は、どう伝えるかという「書く」フェーズを通じて世界に表現する。この際に「伝わりやすい工夫」が求められる。一意に伝わる命名、読み手の記憶リソースを割かないための考慮、そして視覚的な明瞭さをもたらすレイアウトの美しさ。これらは、まさに『リーダブルコード』が具体的に教えてくれるTipsが、いかに「低負荷で」「正しく」伝えるための本質的な要素であるかを物語っている。

テクニック例	低負荷で伝える	正しく伝える	説明補足
意味の明瞭な命名（例：`positive_numbers` / `calculate_average_of_positive_numbers`）	◎	◎	名前だけで役割が伝わる。読者がコードを読む前に理解できる。
早期リターン（例：`if not x: return`）	◎	△	不要な分岐を即排除し、追うべきロジックが減る。
スコープを最小に保つ変数設計	◎	○	一度使った変数を気にし続ける必要がなくなる。

このように、本記事で解説した情報伝達の普遍的な原則は、『リーダブルコード』で紹介される具体的なテクニック一つ一つの「なぜ」を深く理解するための強固な土台となるはずだ。

より良いコードを書くための意識は単に技術的なスキルを高めるだけでなく、未来の自分やチームメンバーへの円滑なコミュニケーションを追求する行為である。今日からあなたのコードに、この「伝える」意識を最大限に宿らせてほしい。

蛇足：FBの歓迎

私の作文能力の低さ故に、本記事が皆様へ「高負荷で」「正しくない」伝わり方をしている可能性があります。その場合、より良い記事へしたいので、皆様のご意見をコメントで頂けたらと考えています。よろしくお願いいたします。