Zenn
💯

100点満点のコードレビューを目指して

2024/11/28に公開
コードレビュー
idea

コードレビューは一般的に変更内容となるコードがコードベース入る前の門番のような役割を担っています. またコードレビューはコード作成者に対するフィードバックの形をとるため, ネガティブなものになりやすいです. コードレビューはとてもよく普及したエンジニアリングプラクティスにもかかわらず, 上述の通りあまり良い印象を持たれていません. コードレビューがこのような不快なやり取りになってしまう原因は情報の非対称性にあります. ここでは情報の非対称性を解消してコードレビューを100点満点にする方法を考えます[1].

コードレビューの目的

そもそもコードレビューで100点満点を取るには何を基準にすればよいのでしょうか. 『Googleのソフトウェアエンジニアリング』ではコードレビューには以下のような効果があると述べられています.

  • コードの正しさをチェックする
  • コードの変更が、他のエンジニアにとって意味を把握できるものであることを保証する
  • コードベース全体での一貫性を強制する
  • チームのオーナーシップを心理的に促進する
  • 知識共有を可能にする
  • コードレビュー自体の履歴の記録を提供する

ここで100点満点のコードレビューとはコードレビューの中でのやり取りが上にあげられたものだけに関連していることとします. 上にあげられた項目を達成すること自体にも難しさがあります. この観点については多くの文献[2] [3]で議論されているためここでは議論しません. 上述の効果を目的としたやり取りを課題内在性負荷とすると情報の非対称性から生じるコードレビューの難しさは課題外在性負荷ととらえることができます[4]. つまり本稿ではコードレビューにまつわる課題外在負荷を下げるための方法について考えていきます.

コードレビューの中に存在する情報の非対称性はコードレビュアーとコードレビュー作成者の2つの対立した立場によって生じます[5]. 以下ではそれぞれの立場が所有する情報を明らかにし, それにまつわる情報非対称性を解消していきます.

コードレビュアー

レビュアーはコードベースに対するオーナーシップを持っているため, コードレビュー作成者と比較して以下のような優位性を持っているでしょう.

  • コードベースに対する理解
  • エンジニアリング全般に対する知識

よってレビュアーがコメントする際には上に挙げた観点にもとづいて具体的で参照可能なエビデンスを伴うべきです.

反復処理はすでに foo.ts で for...of が使用されているため, コードの一貫性の観点から for...of を使うことが望ましいです.

上述のような知識・理解はコードレビュアーとコードレビュー作成者との間で大きな差がある場合, そもそもコードレビューが成り立たないということも考慮する必要があります. 例えばコードベースそのものが巨大で変更内容の影響範囲が大きい場合やふるまい駆動開発 (BDD)[6] のような知識概念から理解する必要がある場合が考えられます. この場合はコードレビュアーがコードレビュー作成者に対して学習機会を与える必要があるでしょう.

またコメントに対して明確なエビデンスを用意できない場合があります. 常識や社会学的通念にもとづく内容は根拠を挙げるのが難しいかもしれません. こういった観点はユーザービリティやAPIの利便性, 開発者体験に影響する内容の可能性があります. この場合はコードレビュー上で議論するよりも別の方法で議論するべきかもしれません.

それとは別に直感的に生まれたコメントもあるでしょう. その場合は個人の意見(IMO)であることを明記しましょう. 意見を述べることそのものは悪いことではなく, より良い議論を促すかもしれません. 問題はコメントの依拠が不明瞭となることでコードレビュー作成者の主権を阻害してしまうことにあります. コードレビュー作成者がどんな行動をとることができるかということを考えてコメントするとよいでしょう.

コードレビュー作成者

コードレビュー作成者はコードレビュアーよりも以下の知識を持っています.

  • 変更内容に対する理解
  • 変更内容の経緯

特に変更を行ってすぐは知識の呪いにとらわれている可能性が高いです. あらかじめ説明すべき観点を挙げておき, それに従った説明を書けるようにしましょう.

またコードレビュー作成者が自身でコードレビューを行うように事前にレビュー内容を改めて確認するのもよいでしょう. コードレビュー作成者も「コードレビューの観点」について熟知しあらかじめ説明できるようにすべきです. 単に確認だけで終わらせず, 「なぜそうしたのか」や「なぜそうしなかったのか」ということをコメントに書くとレビュアーに対する理解の共有となります.

また熟練したエンジニアはコードを読むとき, より大きなチャンクで読むことができるといわれています[7]. レビュアーはコードレビューを行うときにコンテキストに注目してコードを眺めていることが多いです. よってコードレビュー作成者は変更内容の中でコンテキストの違いについてよく説明するべきです.

変更内容をきちんと説明できない, 経緯を理解していないような場合はコードレビューが成立しないでしょう. このような場合はコードレビューの前に他の方法をとるべきです.

ここまででコードレビューに存在する情報の非対称性について注目し, これを減らす方法について考えてきました. 100点満点のコードレビューを目指すには上述の内容を意識して最善を尽くすべきですが, リソースには限界があります. そもそも情報非対称性が生まれないように, ペアプログラミングといったコードレビュー以外の方法も活用し, 最適なコードレビューを行いましょう.

脚注

  1. コードレビューはつまらないから丁寧なプルリクエストでチームの生産性向上を目指す | blog.tai2.net https://blog.tai2.net/how-to-code-review.html コードレビューはなぜつまらないのか, またレビュイーがコードレビューの内容について多くの情報量を持っていることについて述べられています. ↩︎

  2. Googleのソフトウェアエンジニアリング―持続可能なプログラミングを支える技術、文化、プロセス, Titus Winters, Tom Manshreck, Hyrum Wright, 竹辺 靖昭, 久富木 隆一, オライリー・ジャパン, 2021 https://www.oreilly.co.jp/books/9784873119656/ ↩︎

  3. コードレビュー開発者ガイド | google-eng-practices-ja, https://fujiharuka.github.io/google-eng-practices-ja/ja/review/, Google Engineering Practices Documentation | eng-practices の日本語訳 ↩︎

  4. 認知負荷(Cognitive load) Cognitive load - Wikipedia, https://en.wikipedia.org/wiki/Cognitive_load, 認知負荷がプログラミングに与える影響については『プログラマー脳 ～優れたプログラマーになるための認知科学に基づくアプローチ』(Felienne Hermans, 水野 貴明, 水野 いずみ, 秀和システム, 2023 https://www.shuwasystem.co.jp/book/9784798068534.html)を参照. ↩︎

  5. 「コードレビュアー」と「コードレビュー作成者」という用語はコードレビュー開発者ガイド | google-eng-practices-jaに準拠しています. ↩︎

  6. Behaviour-Driven Development - Cucumber Documentation https://cucumber.io/docs/bdd/ ↩︎

  7. プログラマー脳 ～優れたプログラマーになるための認知科学に基づくアプローチ, (Felienne Hermans, 水野 貴明, 水野 いずみ, 秀和システム, 2023 https://www.shuwasystem.co.jp/book/9784798068534.html ↩︎

Discussion