こんにちは まだ読んでいる最中ですが最近会社内の輪読会で読んでいる本の復習として記事をまとめさせていただきました！ 著者はAdrienne BraganzaさんでタイトルはLooks Good to Meです 2025年4月現在は翻訳されていない本になります。早く日本語版読みたいですね！
コードレビューの目的
まずはなぜ、コードレビューを行う必要があるのかを確認しましょう。
A code review is a process software developers use to inspect each other’s code, making sure it passes a set of agreed-upon standards.
コードレビューとは、ソフトウェア開発者がお互いのコードを検査し、合意された一連の基準に合格していることを確認するためのプロセスである。(DeepL翻訳)
引用元 Adrienne Braganza (2024) "Looks Good to Me" Constructive code reviews p44
合意された一連の基準とは
- コーディングルール
- コード品質
- テストコードの網羅性
- パフォーマンス要件
- 可読性
などチームで開発を行う上でこれは守ろうねがあるはずです。
このチームで決めたお約束がしっかりと守れているよね？という確認を行う工程がコードレビューです！
そのほかにも、コードレビューの良い点として挙げているものがありました！
With code reviews, the opportunity to share and transfer knowledge between all involved naturally presents itself. Knowledge transfer and knowledge sharing can lead to more people on your team understanding a larger percentage of your codebase. With more knowledge equally spread across the team, you can reduce the overall team’s dependency on specific team members.
コードレビューでは、関係者全員が知識を共有し、移転する機会が自然に訪れます。知識の移転と共有は、チームのより多くの人が、コードベースのより多くの割合を理解することにつながります。より多くの知識がチーム全体に均等に行き渡ることで、チーム全体の特定メンバーへの依存度を下げることができる。(DeepL翻訳)
引用元 Adrienne Braganza (2024) "Looks Good to Me" Constructive code reviews p42
コードレビューには
- 実装が基準を満たしているのかチェックを行う
- 実装や機能に対する知識の共有
という目的があるわけですね！
これだけ聞くとコードレビューは必ずやらないといけないねと皆さん思うはずですが、 現実ではめんどくさいとみなさん思ってしまいがちだと思います！
ではなぜめんどくさいと思ってしまうのでしょうか？？
Let’s be clear about something: most software development teams are not against a code review process, just the annoyances that surround it.
はっきりさせておきたいことがある。ほとんどのソフトウェア開発チームは、コード・レビュー・プロセスに反対しているのではなく、それにまつわる煩わしさに反対しているだけなのだ。(DeepL翻訳)
引用元 Adrienne Braganza (2024) "Looks Good to Me" Constructive code reviews p42
皆さんも経験あると思います！
「コードレビューをするぞ〜〜！」とプルリクを意気揚々と開いた次の瞬間、 変更行：2000、変更ファイル：25とか表示された瞬間に、「あー・・・やっぱりいまやってるタスク終わってから見ようかな」とか思ったこと皆さんありますよね！そしてそのプルリクは放置されて催促されるとか。
ほかには プルリクの説明にはチケットのリンクが貼ってあるだけとか、プルリクに何も書いていないとか、コードが複雑すぎて何をしているかわからないとか、プルリクに関係ないものがコミットに含まれているとか・・・
煩わしさには
- プルリクの大きさ
- プルリクの情報
- プルリクの複雑さ
これだけではないとは思いますがパッと思いつくもので言うとこんなパターンですかね！
ではこの煩わしさを改善するためにするべきことは何なのか！
ルールを作ろう！
"Looks Good to Me"ではコードレビュープロセスを立ち上げるための根本的なルール決定の手法から プルリクの作り方まで様々なルールの決め方やコードレビューのセオリーなどコードレビューに対するさまざまなアプローチ、改善方法が書かれています。 本来であればこれらのルールをチーム内で決めた上でコードレビューに取り組むべきです！！ これらを取り決めるには時間が必要な上私自身まだ"Looks Good to Me"を読みきれていません。
なので今回は個人で行えるレビュアーに優しいプルリクの作り方について掘り下げていただきます！ それぞれの煩わしさに対して個人でアプローチできることはあるのか？ 見ていきましょう！
プルリクの大きさ
大きいプルリクはそもそも悪いものなのでしょうか？
gargantuan PRs are submitted with the expectation that the reviewer will give it a quality review. The truth is, the larger the PR, the lower the incentive for the reviewer to actually look at it, let alone thoroughly review it
巨大なPRは、レビュアーが質の高いレビューをしてくれることを期待して提出される。実際のところ、PRが大きければ大きいほど、査読者が実際にそのPRに目を通すインセンティブは低くなる。(DeepL翻訳)
引用元 Adrienne Braganza (2024) "Looks Good to Me" Constructive code reviews p90 p91
質の高いレビュー、早期のフィードバックを望むのならばプルリクの変更内容は小さくするべきというこということですね！ ではどれくらいの小ささが妥当なのでしょうか？
One reliable guideline: don’t submit more than 500 total lines of code in a PR. In fact, that’s more of a hard upper bound; try to stay way below that!
1つの信頼できるガイドライン：PRで提出するコードの総行数は500行を超えないこと。実際には、これはむしろ厳しい上限であり、それ以下にとどまるようにしてください！(DeepL翻訳)
Another reliable guideline: keep your PRs below 20 total files changed.
もうひとつの信頼できるガイドラインは、PRを変更されたファイルの合計数が20以下に保つことだ。(DeepL翻訳)
引用元 Adrienne Braganza (2024) "Looks Good to Me" Constructive code reviews p94
他にもプルリク大きさについて"Looks Good to Me"の中で触れられていましたが、わかりやすい大きさの単位はズバリこれでした。 そして何より大切なのは
500行、20ファイルという変更の上限は限界値で変更は小さければ小さいほど良い
ということです。
プルリクが大きくなってしまう理由はなんでしょうか？ 私が実際にプルリクをコードレビューするときに遭遇するケースとしては
- 実装している機能が多い
- ついでにの修正や実装が混ぜ込まれている
が多いです。
なので、1つのプルリクで実装タスクを完了させようという考えをまず捨てる必要があります。 実装を適切な大きさに分割してプルリク作る判断をするのに慣れていない場合は実装を行う前に「今、作業を行うブランチではどこまで実装を行うのが適切だろうか？」を検討することが良いと思いました。 同僚や、上司に相談するのも良い手かと思います。（ただし、この場合はプルリクは細かい方がいいよね！という考えがチームに浸透していないといけません。）
注意する点としてはコードレビューしてもらう場合に過去のプルリクを頻繁に意識しないと適切なコードレビューができない場合それは複雑なコードレビューに繋がってしまいやはりコードレビューに煩わしさが伴ってしまいます。 そしてこの種の煩わしさを解消にするにはプルリクのコンテキスト（概要や目的、背景など）を丁寧に書く必要があるかプルリクの粒度が適切でない場合があるので見直す必要があるのかなと考えました。
すなわち、意味のある最小の機能でプルリクを作ることが質の高いコードレビューにつながります。
プルリクの情報
プルリクのコンテキストはどうあるべきなのでしょうか？
Always err on the side of more detail and context in your PR. Make it so clear that if you were to submit this PR and go on vacation, no one would need to contact you to clarify something!
PRでは常に、より詳細で文脈のある方を選ぶこと。もしあなたがこのPRを提出して休暇に入ったとしても、誰も何かを明確にするためにあなたに連絡する必要がないくらい明確にしましょう！(DeepL翻訳)
引用元 Adrienne Braganza (2024) "Looks Good to Me" Constructive code reviews p96
以下の項目が書いてあれば明確なPRと言えるのではないでしょうか！
- 概要：プルリクの簡単な説明
- 目的：このプルリクをマージすることで達成される目的は？
- 背景：プルリクを作ることに至った理由やPRの実装に至った理由は？
- 影響範囲：このプルリクが影響するモジュールや機能は？
- 動作確認内容：動作確認はどのようにおこなったか？
- 補足情報：設計ドキュメント・関連リンク・変更前後のスクリーンショットなど
プルリクを作ることに対してここまで時間をかける必要があるのかという疑問が湧くかもしれないですが、 レビュアーが複数いるのであればレビュイーが時間をかけてプルリクを作ることに意味はあると思います。 なぜならば、理解のしやすいプルリクを作ることはレビュアーがレビューに費やす時間の削減につながります。 複数人のレビュアーが各々でプルリクの上記で上げている書いてあるべき項目を推測や探したり時には対面でレビュイーに確認しながらレビューを行うと時間がかかってしまいます。 つまり明確なプルリクを作ることはチームのレビュー工数を削減するということに対してレバレッジが効く作業になる考えています！
そして何より、こういった項目を記載するのは未来の自分のためでもあります！ コードの調査を行った際に過去のプルリクの内容を確認する必要がある時にプルリクに何も書かれていないと困るのはプルリクを作った自分自身やチームメンバーになるのではないでしょうか？
「書かれていなくても分かるだろう」ではなく「何も知らない人が読んでも理解できる」レベルでの説明を意識することが大切ですね。 最初これらの項目に対しての的確、適切に書くことは難しいと思いますが、やはりこういったものを書く力は数をこなして感覚を掴む必要があると思います。
プルリクの複雑さ
プルリクの複雑さについては前述している、プルリクの大きさとプルリクに書く情報が守られていれば ある程度、防げるのではないかと考えています！
しかし、どうしてもプルリクの内容だけでコードレビューすることが難しいケースはあると思います コードレビューはプルリク上で完結させるという厳格なルールを設定していないのであれば 対面コードレビューなどの別アプローチが効果的だと思います。
なのでこういうケースはこうやってコードレビューをしようという柔軟さが必要ですね！
最後に
私自身、コードレビューはなんとなくでやっていたりしているところがあったのですが なぜコードレビューを行うのかという動機づけを行うにはとても良い本です！ 引き続き、輪読会で読んでいきたいです！
輪読会について毎週1日はできているので会社の人と交流を図る良い機会にもなっています！ 日本語訳がない本だったので輪読会で書かれていることの解釈をみんなで確認しながら読むのはとても理解に役立ちます！ 輪読会の度に翻訳してくれているH.A.さんいつもありがとう！
最後まで読んでくださりありがとうございます！
この記事を読んで興味を持って下さった方がいらっしゃればカジュアルにお話させていただきたく、是非ご応募をお願いします。
iimon採用サイト / Wantedly / Green
