【エンジニアあるある】コードレビューで指摘された箇所、実は仕様だった
こんばんは！IT業界で働くアライグマです！
エンジニアなら誰しも経験があるのではないでしょうか。
コードレビュー中に「ここの処理、バグでは？」と指摘され、確認してみると…「仕様通りです」というオチ。
- 「この計算式、間違ってません？」→ 仕様です
- 「このAPI、なぜこんな挙動？」→ 仕様です
- 「この変数名、もっと分かりやすくできませんか？」→ 仕様書のままです
コードレビューはバグの早期発見や品質向上のために行われますが、指摘が実は正しい動作だったというケースも少なくありません。
なぜこのようなすれ違いが発生するのか？ どうすれば防げるのか？
この記事では、コードレビューで「これは仕様です」を減らすための工夫や対策を紹介します。
なぜ「仕様です」が起こるのか？
仕様が十分に共有されていない
コードレビューで「バグでは？」と指摘される原因の一つが、仕様がチーム内で十分に共有されていないことです。
- 仕様書はあるけれど、読まれていない
- 口頭で伝えただけで、ドキュメント化されていない
- 「過去の経緯」を知っている人が限られている
仕様がドキュメント化されておらず、知識が個人に依存していると、レビュー時に誤解が生じやすくなります。
仕様が直感的でない（意外な動作をする）
「仕様です」と言われても納得しづらいのは、仕様の挙動が直感的でない場合です。
たとえば、次のようなケースです。
- 「0÷0」を計算したらエラーではなく、デフォルト値の100が返る（仕様書にはそう書いてある）
- ボタンを押すと1秒待ってから処理が実行される（パフォーマンス対策だが、見た目はバグっぽい）
- エラーメッセージが「成功しました」になっている（仕様書の翻訳ミス）
開発者の直感に反する仕様は、コードを読んだだけでは理解しにくく、誤解を生みやすいです。
過去の仕様変更が影響している
「昔の仕様」と「今の仕様」が混在しているケースも要注意です。
- 以前はAの挙動だったが、仕様変更でBになった
- 古いコードが残っており、どちらが正しいのか判断がつかない
- ドキュメントの更新が追いついていない
このような状態だと、「仕様通り」と言われても、本当に最新の仕様なのか疑問が残ります。
「仕様です」を減らすための工夫
レビュー前に仕様を明確に共有する
コードレビューで「これは仕様です」を減らすためには、事前に仕様を明確に共有することが重要です。
仕様書を用意する
- 仕様が確定したら、できるだけ詳細にドキュメント化する
- 変更があったら、必ず更新する
- 可能なら「なぜこの仕様になったのか？」という経緯も書く
プルリクエストに仕様の説明を含める
- PRの説明欄に「この挙動は仕様です」と明記する
- 参考になる仕様書のリンクを貼る
- 実装の背景や意図を簡単に説明する
チームで事前に仕様をすり合わせる
- 仕様が曖昧なまま実装を進めない
- 設計段階で「この仕様で問題ないか？」を確認する
- 不明点があれば、早めに相談する
これらを徹底することで、レビュー時の「これは仕様？」を減らし、スムーズな開発が可能になります。
「直感的でない仕様」はコメントやテストで補足する
どうしても直感的でない仕様は、コードだけでは理解しにくいことがあります。
その場合は、コメントやテストで仕様を明示すると効果的です。
コードコメントに仕様の根拠を記載する
// 仕様書によると、0除算時はデフォルト値100を返す
function calculate($a, $b) {
return $b === 0 ? 100 : $a / $b;
}テストコードで期待される動作を示す
it('should return 100 when dividing by zero', function () {
expect(calculate(10, 0))->toBe(100);
});こうすることで、レビューする側も仕様を理解しやすくなり、余計な指摘を減らせます。
仕様変更があったら履歴を残す
仕様が頻繁に変わる場合は、仕様変更の履歴を残すことが重要です。
- バージョン管理をしっかりする（GitHubのWikiやNotionなど）
- 変更の背景を記録する（「なぜこの変更をしたのか？」を残す）
- 古い仕様と新しい仕様を明確に区別する
特に、「過去の仕様のせいでレビュー時に混乱する」ケースは多いので、履歴を整理することが重要です。
まとめ：「仕様です」を減らして、スムーズなコードレビューを
コードレビューで「これは仕様です」という指摘が多いと、レビューの生産性が下がり、不要なコミュニケーションコストが発生します。
✅ 仕様を明確に共有し、ドキュメントを整備する
✅ 直感的でない仕様はコメントやテストで補足する
✅ 仕様変更の履歴を残し、チーム全体で把握できるようにする
「仕様通りだけど分かりにくい」ではなく、誰が見ても分かりやすいコードと仕様を目指すことで、よりスムーズな開発が可能になります。
次のコードレビューでは、「これバグじゃない？」と言われる前に、「仕様書の○○に書いてあります！」と自信を持って答えられるようにしたいですね。