レビューで止まる実装には、意図が薄いことがある
プルリクを出したあとに、レビューで指摘をもらうことがあります。
その内容を振り返ると、単なる書き方の好みではなく、
「なぜそうしたのか」がうまく説明できない実装で止まっていることが多いと感じます。
自分の中では、良さそうに見えている。
過去にも似た書き方をした気がする。
今の要件なら問題なさそうに見える。
ただ、その判断を言葉にできないまま実装すると、レビューで見事に引っかかります。
「なんとなく良い」は、未来の自分にも伝わらない
実装中は、自分の頭の中に文脈があります。
この画面はこう使われる。
この条件は今後増えなさそう。
この処理は一時的だから深く作らなくてよい。
そう考えて書いたとしても、コードだけ見ると伝わらないことがあります。
コメントを書くかどうか以前に、判断の前提がコードの形に出ていない。
そうなると、レビューする人は不安になります。
「本当にこの条件だけでよいのか」
「ここで例外を握ってよいのか」
「将来増えたときに壊れないか」
この不安は、レビューが細かいから起きるのではなく、意図が見えないから起きるのだと思います。
意図がある実装は、選ばなかった理由も説明できる
意図がある実装は、ひとつの選択肢を選ぶだけでは終わりません。
なぜこの方法にしたのか。
他にどんな選択肢があったのか。
今回は何を優先したのか。
ここまで説明できると、レビューの会話が進みやすくなります。
例えば、少し冗長に見える実装でも、
「今後条件が増えるので、分岐を見える形にした」
と説明できれば、読み手の受け取り方は変わります。
逆に、短いコードでも、
「なんとなく短く書けたから」
だと不安が残ります。
これは 考えるために、まず書く にもつながる話です。
頭の中の判断を外に出して初めて、自分でも検証できるようになります。
レビューコメントは、意図の不足を教えてくれる
レビューコメントを受けると、少し身構えてしまうことがあります。
自分では考えたつもりだった。
急いでいた。
軽い修正のつもりだった。
そういう気持ちもあります。
ただ、指摘を読み返すと、実装そのものより「判断が共有されていないこと」を見てくれている場合があります。
たとえば、次のような指摘です。
- この条件は他のケースでも成り立ちますか
- この例外は握ってよいですか
- ここだけ既存の書き方と違う理由はありますか
- テストケースにこの分岐がないのは意図的ですか
どれも、責められているというより、意図を聞かれている質問です。
そう考えると、レビューは自分の判断をもう一度言語化する場でもあります。
AIで書いたコードほど、意図を人間が持つ
AIに実装を頼むと、形になる速度は上がります。
ただ、AIが出したコードをそのまま採用すると、
「動きそうだから採用した」という状態になりやすいです。
ここで必要なのは、AIに任せない気合いではありません。
AIに書かせたあと、人間側が意図を確認することです。
- この実装は何を優先しているか
- 失敗するとしたらどこか
- 例外ケースはどこまで見ているか
- 将来の変更に耐えられるか
- チームの既存方針と合っているか
AI時代は、コードを書く手間よりも、判断の責任が目立つようになります。
そのため、実装者は「なぜこれでよいのか」を持っていたいです。
レビュー前に一度だけ自分に聞く
最近、自分が意識したいと思っているのは、プルリクを出す前の小さい確認です。
- この実装で守りたいものは何か
- もっと単純な方法はないか
- あえて複雑にした理由はあるか
- レビューで聞かれたら説明できるか
- 未来の自分が読んで困らないか
これを全部文章にする必要はありません。
ただ、一度立ち止まるだけで、指摘される前に気づけることがあります。
予測の生産性とシフトレフト でも書いたように、後で直すより先に気づくほうが楽です。
プルリク本文にも意図を少し残す
意図は、コードだけでなくプルリク本文にも残せます。
長い説明を書く必要はありません。
ただ、レビューしてほしい観点をひとこと添えるだけで、会話は変わります。
- 今回は最小修正を優先しました
- 将来の拡張より、既存挙動を崩さないことを見ています
- この分岐は一時対応なので、後続で整理したいです
- この案以外に迷った選択肢がありました
こうした一文があると、レビューする人は背景を見ながら読めます。
自分の考えを全部説明するというより、読み手の入口を置く感覚です。
コードに意図が出ていて、プルリクにも判断の前提が残っている。
その状態に近づくほど、レビューは指摘の場だけでなく、考えをそろえる場になっていくと思います。
まとめ
レビューで指摘される実装は、間違っているとは限りません。
ただ、意図が伝わらない実装は、読み手に確認の負担を渡してしまいます。
「良いだろう」で書く前に、
「なぜ良いと思ったのか」を一度言葉にする。
それだけでも、実装の質は変わると思います。
自分もまだ何度も忘れるので、プルリク前の小さい習慣として残していきたいです。