はじめに
コードレビューはソフトウェア開発の品質向上やチーム間のコミュニケーションを深めるために重要なプロセスです。しかし、進め方や観点にバラつきがあると、作業効率やプロダクトの品質に影響を与えることがあります。
私たちのチームでは、 「Google Engineering Practices Documentation」 を参考にし、以下の理由から輪読会を実施しました。
-
コードレビューや PR の品質向上
- チーム内でコードレビューや PR の品質を統一し、より高い基準を持つことを目指しました。
-
チーム内での課題意識と輪読会の雰囲気
- チームとしてコードレビューの進め方に課題を感じており、その解決策として自然に輪読会を開催することになりました。
-
多国籍かつ業務委託メンバーを含むチーム体制
- チームは多国籍で、業務委託メンバーも含まれているため、共通の認識を持つことが特に重要でした。
- 直近で新卒 1 名、中途 1 名がジョインしたタイミングで、改めて認識を合わせる良い機会でした。
輪読会の進め方
輪読会の進行は以下のように進めました。
-
ファシリテーター
- 輪読会は筆者がファシリテーターを担当しました。
-
形式
- 当日読書型で実施しました。
- 1 テーマにつき 1 時間を使って計 3 回実施しました。
-
進め方
- 最初の 30 分：参加者それぞれがテーマの内容を読み、その内容について自分の感想や意見、協議したい点を書き出しました。
- 残りの 30 分：発表と意見交換。各自が書き出した内容を発表し、意見交換やディスカッションを行いました。参加者間での考えを共有し、深掘りする時間として活用しました。
テーマ 1：良い PR の説明文を書く
より明確な PR のタイトルにする(First Line)
-
参加者から挙がった意見
- 「PR のタイトルに [TASK] のような接頭辞を付けてラベリングしている。」
- 「案件がわかるように、 [案件名] や、保守系の改修であれば[コンポーネント名]（例： [Catalog] ）や、CI に関連する変更なら [ワークフロー名] を付けている。」
- 「接頭辞で案件名などを付けると、PR の検索性が向上し内容を把握しやすい。」
-
チームで共通認識となったこと
- PR タイトルに案件名などを入れると、PR の検索性向上や内容の把握がしやすくなり、コードレビューがより効率的になる。
本文には有益な情報を書く(Body is Informative)
-
参加者から挙がった意見
- 「UI 改修の場合、修正前後のスクリーンショットを添付するとレビュワーに親切でわかりやすい。」
- 「コンポーネント改修の場合、Storybook の更新も反映していることを明記すると、レビュワーがコードの動作確認がしやすい。」
- 「動作確認が必要な場合、テストアカウントの情報を明記しておくと、レビュワーが実際に動作確認を行う際に親切。」
- 「案件によっては、レビュー時に考慮すべきことや、逆に考慮しなくてよいことが明記されていると、レビュワーが何を注視すべきかを把握しやすい。」
- 「なぜこの対応をするのか（背景や理由）を説明することで、後からレビューする際にもその意図が理解しやすい。」
- 「レビュワーの手間を省き、スムーズなレビューを促進するために、スクリーンショットや具体的な情報を入れて見やすくしている。」
- 「確認して欲しい観点（例えば、特定の機能や動作）を記載し、レビュワーが注力すべきポイントを明確にしている。」
-
チームで共通認識となったこと
- PR の本文には、PR テンプレートを活用して、変更内容や背景、テストアカウント、確認してほしい観点などの有益な情報を必ず記載することが重要。
- スクリーンショットや Storybook の更新情報など、視覚的な資料も活用し、レビュワーが理解しやすい形で PR を作成することも重要。
チームでは以下のような PR テンプレートを活用しています。（一部抜粋）
## 概要
<!-- 変更の目的/関連するJIRAなどのURL -->
## 変更内容
<!-- 本PRでやること -->
## やらないこと
<!-- 本PRでやらないこと -->
## 動作確認
<!-- 必要に応じてスクショによる比較など -->
## 確認方法
<!-- 動作確認の方法 -->
## レビュー観点
<!-- レビュワーに注視して欲しい点など -->
## 参考文献
<!-- 参考文献やURLなどがあれば -->
テーマ 2：PR は小さくする
なぜ小さな PR にするのか。(Why Write Small CLs?)
-
参加者から挙がった意見
- 「PR を見てボリュームがあると、レビュワーはまとまった時間を確保できたときにレビューしようと後回しにしがちなため、結果としてレビューが遅れやすくなる。」
- 「小さい粒度の PR は、レビュワーだけでなく、実装した本人も後で変更を確認しやすく、認知コストを減らせるため全体の作業効率が向上する。」
- 「Issue を作成する際に、『この Issue 単位で PR を作成したらレビューがしやすい』を意識することで、PR の粒度を適切に調整できるようにしている。」
-
チームで共通認識となったこと
- PR は一つの自己完結した変更を意識して作成することが重要。小さな変更を複数回に分けて細かく PR を出すことで、レビューがスムーズに行える。
- Issue 単位で PR を作成すると、変更内容が自然に小さくまとまり、レビュワーも理解しやすく、レビューや実装もしやすくなる。
大きな PR が許されるのはどのようなときか？(When are Large CLs Okay?)
-
参加者から挙がった意見
- 「パッケージなどのバージョン UP で自動生成されたものが含まれる PR」
- 「一緒に出さないと動作しないものや確認が難しいもの」
- 「差分が機械的な変更点のみのもの」
-
チームで共通認識となったこと
- 大きな PR が必要な場合、事前に相談することで、チーム内での認識のずれを防ぎ、スムーズに進めることができる。
- 機械的な差分や自動生成された変更はどうしても大きくなりがちですが、それでも PR が大きくなる理由を説明できると、レビュワーも理解しやすい。
テーマ 3：レビュワーコメントへの対応方法
あなた個人へのコメントだと受け取らない(Don’t Take it Personally)
-
参加者から挙がった意見
- 「コメントを送る前には、一呼吸おいて内容を見直すようにしており、意図が伝わりやすくなるように心掛けている。」
- 「コメントが異なる場合、どれが正しいのか判断が難しいことがある。その場合、複数の意見を尊重しつつ、最終的にどうするかをチームで整理している。」
- 「コードレビューの範囲外（例えば、ルールやプロジェクト全体の運用に関する指摘）は、PR 内ではなく PR 外で議論した方が良い。」
- 「片手間でレビューしていると、コメントが機械的になってしまうので絵文字などを使ってコメントを柔らかくするよう心掛けている。」
- 「言葉遣いは人によるため、レビュワー側が配慮を持ってコミュニケーションを取ることが大切だと感じている。」
-
チームで共通認識となったこと
- 一つのコメントに対して、他にも意見がある場合、結論が出る前に議論に参加し、意見を出し合うことが重要。結論が出てしまうと、後からの意見は開発者にとって負担になる。
- コメントには絵文字や「！」などを追加すると、文が柔らかくなり、相手が安心して受け入れやすくなる。
- レビュイーはコメントに対してそれはプロダクトや自身の成長のためと思える心を備えることが重要。
コードを明確にする(Fix the Code)
-
参加者から挙がった意見
- 「コードが直感的でない場合や複雑な処理が含まれている場合、コメントがあると理解しやすい。」
- 「コメントがなくてもコードを読めばわかる場合もあるが、『読まないとわからないコード』は後々問題になることがある。そのため、コメントがあると、コードの意図や背景を理解しやすい。」
- 「なぜその実装がされているのかの背景がわかるコメントがあると、コードレビューや将来的なメンテナンスがスムーズになる。」
- 「自分が書いたコードでも、時間が経つと内容を忘れてしまうことがあるので、複雑な仕様や処理の実装については、特にコメントを残しておくことが重要。」
-
チームで共通認識となったこと
- コードの実装理由や背景をコメントで明記することで、レビューの際や後にコードを見直す際に役立ち、チーム全体での理解が深まる。
- 自分でも忘れてしまう可能性があるため、特に複雑なコードや一見してわかりにくい部分にはコメントを残し、保守性や他の開発者が理解しやすくすることが重要。
まとめ
私たちのチームで実施した 「Google コードレビューガイドライン」の輪読会を通じて学んだポイントを紹介しました。
振り返ってみると、コードレビューは単なるバグ修正やコードの最適化に留まらず、チーム間の認識の共有や、開発フロー全体の品質向上にもつながる重要なプロセスであると再認識しました。
輪読会を通じて得た学び
輪読会を通じて以下の学びが得られました。
- PR の品質向上：タイトルや本文に必要な情報を盛り込み、レビュワーが迅速かつスムーズにレビューできる環境を整える。
- PR の粒度：小さな PR を心がけることで、レビュワーとレビュイー双方の負担を軽減し、作業効率を向上させる。
- 協力的なレビュー文化：コメントへの対応方法や意見交換の大切さを再確認し、レビューを単なる指摘に留めず、チーム全体でより良いコードを作るための協力の場として活用する。
おまけ
輪読会の中で、ZOZOTOWN 内でそれぞれの良い PR と思うのものを持ち寄って共有する場もありました！どこがいいのか、わかりやすいのか、真似したいのかなど様々な意見交換ができて面白かったです！
みなさんも是非 Google コードレビューガイドラインの輪読会を実施してみてください！
Discussion