これは好みの問題でも、言い方の問題でもありません。
レビューという行為の定義から外れているというだけの話です。
この記事は、
- 抽象的なレビュー指摘をしてしまう人
- それを「なるほど」と受け取ってしまう初心者
- そして、なんとなく違和感を覚えつつ言語化できていなかったベテラン
全員に向けて書いています。
「可読性」という言葉は、なぜここまで無責任なのか
まず事実確認をしましょう。
可読性は測定不能な指標である。ということです
- 何行以下なら高いのか？
- ネストはいくつまでか？
- どの知識レベルの人間を想定しているのか？
これらが定義されていない「可読性」は、指標ですらなく、ただの感情のラベルです。
そしてレビューで感情ラベルを貼った瞬間、
- 議論は止まり
- 学習は起きず
- 改善も再現されない
それはレビューではなく、単なる感想でしかありません。
読めないコードの正体は、ほぼ100%「前提知識」だ
コードが読めない理由は、ほぼ例外なくこれで説明できます。
コードが要求している前提知識と、読み手が持っている前提知識が一致していない
可読性の問題ではありません。
- ドメイン知識を知っている前提
- フレームワークの内部仕様を知っている前提
- チームローカルな命名規則を知っている前提
これらが暗黙のまま埋め込まれていると、「読めない」という体験が発生します。
そこで言うべき言葉は、「可読性が低い」ではありません。
「可読性が低い」は、読んでいない証拠である
本当にコードを読んだレビュアーは、「可読性が低い」とは言えない。
なぜなら、しっかり読めば必ずこうなるからです。
- どこで理解が止まったかがわかる
- 何を知らないと読めないかが見える
- 自分の認知負荷の正体を自覚する
それを言語化せずに、
「可読性が低いですね」
で済ませるのは、
- 読んでいないか
- 読んだが考えていないか
- あるいは説明する能力がないか
そのいずれかです。
良いレビューは「認知負荷」を特定する
レビューでやるべき仕事は、実は一つしかありません。
どこで、どんな認知負荷が発生しているかを特定し、言語化することです。
具体的にはこう。
- 「この関数は3つの概念を同時に保持しないと追えない」
- 「この条件分岐は、ドメインルールを頭の中で復元する必要がある」
- 「この命名は、実体を想像するまでにワンステップ余計にかかる」
ここまで言って、初めてレビューになります。
ベテランにとって「可読性が低い」は重罪である
ベテランがこの言葉を使うとき、罪はさらに重くなります。
なぜならそれは、
- 自分の暗黙知を
- 他人も持っている前提で扱い
- それを説明しないという選択
をしているからです。
ベテランの役割は、「わかる人だけがわかる世界」を維持することではありません。
暗黙知を言語化し、再利用可能な知識に変換することです。
それを放棄して「可読性が低い」と言うのは、立場を使った責任転嫁に等しいものです。
レビュー指摘は「再現可能」でなければならない
良いレビュー指摘には、必ず再現性があります。
- 他の人が読んでも同じ指摘ができる
- 同じ条件なら、誰でも同じ認知負荷を感じる
- 修正後、何が改善されたか説明できる
「可読性が低い」は、これらを一つも満たさないのです。
再現性のない指摘は、
- ナレッジにならない
- ルールにならない
- チームを強くしない
つまり、ただのノイズとなります。
じゃあ、どうレビューを書けばいいのか
NGレビュー
可読性が低いです。
OKレビュー（最低限）
この処理は、◯◯の仕様を知っていないと意図が読み取れません。
コメントを補足するか、命名で前提を明示した方が良さそうです。
良いレビュー
この関数は
- ドメインAの知識
- ライブラリBの挙動
- 呼び出し元の制約
を同時に保持しないと理解できません。
読み手を「新規参画メンバー」と想定すると、ここがボトルネックになります。
ここまで書いて、初めて真のレビューとなります。
「可読性」という言葉を使っていい、唯一の条件
それでも「可読性」という言葉を使いたいなら、条件があります。
必ず「誰にとって」「なぜ」をセットで言語化できることです
例：
新規参画メンバーにとって、
この命名はドメイン知識がないと解釈できず、
読み進める際の認知負荷が高いです。
これなら、ギリギリレビューとして成立します。
初心者エンジニアへ
「可読性が低い」と言われたとき、落ち込む必要はありません。
それは多くの場合、「うまく説明できない」というレビュアー側の失敗だからです。
こう聞いても良いと思います。
- 「どの知識があれば読めますか？」
- 「どこで理解が止まりましたか？」
- 「誰を読み手として想定していますか？」
答えが返ってこないなら、そのレビューは無視して問題ありません。（責任は負いませんが）
結論
可読性が低い、はレビューではなく感想だ。
レビューとは、
- 読めなかった理由を
- 再現可能な形で
- 他人に渡す行為
それができないなら、「可読性」という便利な言葉を使う資格はありません。
それは、エンジニアとしての怠慢です。