コードレビューガイドラインをチームで作り上げた話

こんにちは！
Agency 事業部にてシニアシステムエンジニアをしている遠藤です。
最近、私が所属するチームでコードレビューガイドラインを作成しました。
今回は、そのガイドラインをどのように定めたのか、そして具体的にどのようなガイドラインができあがったのかを紹介したいと思います！

背景・きっかけ
コードレビューガイドライン
ガイドライン作成の進め方
認識合わせに苦労した項目について
- コードレビューのスピードについて
- コードレビューの基準について
ガイドラインを運用してみてよかった点
これからの展望
おわりに

背景・きっかけ

私たちのチームでは、DX Criteria を利用して、定期的な自己評価を行っています。
その中には、明文化されているコードレビューガイドラインが存在するかという評価項目が含まれています。
しかし、我々のチームではこれまでコードレビューのルールや基準が明文化されていない状態でした。
それぞれが各自の経験や感覚に基づいてレビューを行っており、その結果、レビューの質やスピードにおいてばらつきが生じていました。
この状況を改善すべく、そして DX Criteria の評価項目を満たすために、我々はコードレビューガイドラインの作成に取り組むことにしました。

コードレビューガイドライン

こちらが実際に定めたガイドラインになります。
Google が定めたコードレビューガイドラインをもとにして、追加や独自のルールが必要な部分についてまとめました。
ガイドラインの項目だけでわかりにくいものには、具体的な行動例を記載しています。

項番	カテゴリ	ガイドライン項目	具体的な行動例
1	コードレビューのスピード	（目安として）コードレビューは1営業日以内に最初の返事を返そう	GitHub PR のコメントにてここまでは見ましたー今日は会議が多めなので明日確認します明日まで見れそうにないので急ぎの場合は代わりに誰かアサインお願いしますこちらのコメントした内容について修正され次第確認します
2	コードレビューのスピード	コメント付き LGTM を活用しよう	GitHub PR のコメントにてコメントした点について修正してもらえればOKなので承認しておきます！
3	コードレビューのスピード	大きな CL（※ Change List: 変更リスト）が来たら… 小さな複数の CL に分割してほしいという依頼を出してみよう分割が難しそうならレビューに時間を要することを伝えよう	GitHub PR のコメントにて変更箇所が多いので、A機能とB機能に分けてPR出してもらえないでしょうか？分割が難しそうならレビューに時間を要しそうです。
4	コードレビューのスピード	タスクに集中しているときに無理にレビューせずタスクに集中しよう	自分の仕事に一休みできるタイミングが来るのを待つ現在のコーディングのタスクが完了した時ランチが終わった後ミーティングから帰ってきた時 microkitchen から帰ってきた時
5	コードレビューのスピード	コードレビューの基準やコードの質を保とう
6	コードレビューのスピード	緊急事態のときは品質に関わるガイドラインは緩和しようバグ修正期日が決まっている機能追加、修正	Slackにて現在障害が発生しており、ユーザに影響があるので急いでリリースしたいので確認お願いします
7	コードレビューの基準	CL が作業対象のシステムのコード全体の健全性を具体的に向上させる状態に一度でも達したならば、たとえその CL が完璧なものでなくても、レビュアは承認しましょう
8	コードレビューの基準	プログラミング言語やフレームワーク、ソフトウェア設計の一般的な原則について共有しよう（メンタリング）	GitHub PR のコメントにて単一責任の原則（Single Responsibility Principle, SRP）という、1つのクラスは1つの責任を持つべきであるという原則があります。これは、1つのクラスが複数の責任を持つと、クラスが大きく複雑になり、変更が難しくなる可能性があるので避けましょうという原則です。
9	コードレビューの基準	ソフトウェア設計の標準的な原則を重視しよう（原則）スタイルガイド（コードフォーマット）原則 SOLID原則 SRP 単一責任の原則 OCP オープン・クローズドの原則 LSP リスコフの置換原則 ISP インターフェース分離の原則 DIP 依存性逆転の法則 KISS（Keep It Short And Simple） YAGNI（You Aren't Going to Need It） DRY（Don't Repeat Yourself） PIE（Program Intently and Expressivery） SLAP(Single Level of Abstraction Principle)	GitHub PR のコメントにて rubocop を実行してください YAGNIの原則に反するのでこの機能は実際に必要となるまでは追加しないでください。
10	コードレビューの基準	Pull Request 内の議論でコンセンサスを得るのが難しい場合は、対面のミーティングやビデオチャットを使おう。それでも解決できない場合は、他のメンバーやマネージャーに相談しよう	GitHub PR のコメントにてコメントのやり取りが3往復以上したら危険信号 2往復くらいはある話が込み入ってきたので一度 Zoom でお願いします。
11	コードレビューで何を期待するべきか	動作検証が難しい場合はデモの提供を依頼する	動画キャプチャーの提供モブプロ形式で確認させてもらうステージング環境にデプロイしてもらって確認させてもらう
12	コードレビューで何を期待するべきか	簡易なコードを説明する what コメントは削除を提案してもよい
13	コードレビューで何を期待するべきか	コードを読むのが難しい場合は開発者に伝え理解できるようアシストしてもらう
14	コードレビューで何を期待するべきか	複雑なCLのレビュー依頼時は少なくとも一人詳しい人をアサインする
15	コードレビューで何を期待するべきか	コンテキストを把握する上で必要な情報があればレビュアに与える
16	レビューでCLをナビゲートする	CL の説明をちゃんと書こうコードを見る前にレビューの1段階目があるイメージレビュー対象としてCLの説明も含んでいる
17	レビューでCLをナビゲートする	前提として大きなCLを出さざるを得なかった場合レビュー依頼事に「メイン」となる部分をCLの説明に含める
18	レビューでCLをナビゲートする	CL に大きな設計上の問題があった場合、気づいた段階で開発者を引き止める
19	コードレビューのコメントの書き方	やさしさを持ちましょう。
20	コードレビューのコメントの書き方	あなたの考えの論理を説明しましょう。
21	コードレビューのコメントの書き方	問題を指摘して明確な方向性を示すことと、開発者自身に決定させることのバランスを取りましょう。
22	コードレビューのコメントの書き方	レビュアのあなただけに複雑なコードの意味を説明させるのではなく、代わりに開発者に対して、コードをシンプルにしたりコードにコメントを追加してもらうようにしましょう。
23	コードレビューでの反対の扱い方	指摘された内容をそのCL内で対処できない場合には、開発者はそのクリーンアップに対して issue を作成し、その issue を自分自身にアサインする

ガイドライン作成の進め方

ガイドライン作成に当たり、参考にしたのは Google が公開しているエンジニアリングプラクティスです。
この中には、コードレビューガイドラインについての詳細なドキュメントが含まれています。
今回はそれの日本語訳されたドキュメントを活用させていただきました。

本ガイドラインはその中の「コードレビュアのためのガイド」のセクションを基に作成しました。
このセクションは以下の項目ごとにまとめられています。

コードレビューの基準
コードレビューで何を期待するべきか
レビューで CL をナビゲートする
コードレビューのスピード
コードレビューのコメントの書き方
コードレビューでの反対の扱い方

これらの項目ごとに、以下のようなフローで「ガイドライン策定会」を行いました：

最初に、全員でドキュメントを読む時間を設定しました。集合後、約10〜15分を読む時間としました。
読んだ内容に基づき、それについて議論を行いました。この議論を通じて、我々のチームに適した具体的なガイドラインを策定していきました。
議論の結果を基に、コードレビューガイドラインを文書化しました。基本的には Google のコードレビューガイドラインに従い、特に重要と感じた項目をピックアップし、それをガイドライン項目として記載しました。

ガイドライン策定会は、週に1時間設け、全員（9名）が集まる形で進行しました。
私がファシリテーターの役割を担い、我々自身の経験や状況に合わせたガイドラインの作成を進めました。

認識合わせに苦労した項目について

今回、9名のチームメンバーでドキュメントの読み合わせと議論を行いましたが、全員の認識を一致させることが難しい場面もありました。
一部ですが、以下に具体的に定めることが難しかった項目について記載します。

コードレビューのスピードについて

Google のガイドラインでは「集中状態にあるタスクがない場合には、レビュー対象のコードが来たすぐ後にコードレビューを行う」ことが推奨されています。
しかし、我々の想定以上に早く、1営業日以内にレビューをすることが定められていたため、チームガイドラインとしてどう定めるか決定するのに難航しました。
これまで比較的大きな CL を含む Pull Request が出されることも少なくなかったため、レビューについてもそれなりに時間がかかっていました。
そのため、コードレビューの質を落とさずに今まで以上に早くレビューを完了させることは難しいように感じられたのです。
結論として、コードレビューは「少なくとも1営業日以内に最初の返事は返すようしよう」と定め、慣れてきた時点でまた見直すことになりました。

コードレビューの基準について

我々のチームでは複数のサービスを開発・運用しており、サービスごとに主担当者が決まっています。
コードレビューにおいては主担当とそれ以外のメンバー2人で見るルールで運用していました。
そのため、自分が担当していないサービスのレビューをどの程度まで行うべきか、という議論も発生しました。
コードの意図や背後にあるビジネスロジックを理解してレビューするのには時間を要するためです。
結論として、主担当でないメンバーがコードレビューを行う際は、仕様の理解を求めず、ロジックが正しいかどうかを確認するように定めました。

ガイドラインを運用してみてよかった点

ガイドラインを運用してみて、我々のチームにはいくつかの良い変化がもたらされました。以下に実際の例を挙げます。

適切な大きさの CL

ガイドラインの導入以前は、CL が大きい Pull Request が出されることが多かったため、レビューに時間がかかる状況がありました。
しかし、ガイドラインの導入により、レビュアを意識した適切な変更量の PR を作成するようになりました。
これにより、レビューがよりスムーズに進むようになりました。

褒める文化

ガイドラインの導入をきっかけに、良いコードや良い行動を積極的に褒めるコメントが増えました。
以前はあまり見られなかったこの文化が、ガイドラインの導入によって根付き、チームの雰囲気が一層良好になってきたと感じています。

レビュー待ち時間の削減と心理的な健康状態の改善

ガイドライン導入以前はレビュイー側からするとレビュー依頼後、レビュアがレビュー開始からコメント、または承認するまでの間、レビュー状況が分からない時間が存在していました。
この時間はレビュイーからすると、精神衛生上良いものではなかったと考えています。
これが現在は、ガイドラインで「1営業日以内に最初の返事をする」ことを明記したことで、レビュー着手時期は長くとも1営業日以内になり、レビュー待ち時間の削減とチーム全体の心理的な健康状態が改善されたと考えています。
また、軽微な修正内容の場合はコメント付きで LGTM をすることや、Pull Request が大きすぎる場合は分割するようレビュイーに依頼することなど、レビュアが短時間でコードレビューに着手しやすくなるような項目もレビューのスピードアップに良い影響を与えていると思います。

これらの変化は、一部ですが、コードレビューガイドラインの運用によってもたらされた大きな成果であり、チームの生産性と健康状態の向上に大いに貢献しています。

これからの展望

コードレビュー策定のための議論を通じて、チーム全体のコードレビューに対する理解が深まり、結果的に良い状態を生むきっかけとなったと感じています。
ガイドラインの導入と運用から得られた経験をもとに、今後の展望を以下のように考えています。

Findy Team+ による定量的な評価

ガイドラインの導入前はリードタイムやデプロイ頻度を計測するツールを導入していなかったため、ガイドライン導入前後においては定量的に開発生産性を計測することが難しい状況にありました。
現在は Findy Team+ の導入が済んでいるため、開発パフォーマンスを定量的に評価し、ガイドラインの改善、更新をチームで進めていきたいと考えています。