【はじめに】
いつも記事をご覧いただきありがとうございます。株式会社Kaienでシステムエンジニアとして働いている島田と申します。
弊社では、開発チームで定期的に輪読会を実施しています。今回は私が担当し、「コードレビューの目的と、実装・PRの粒度の最適化」というテーマを扱いました。
👀今回書くこと
この記事では、輪読会の内容をもとに、
- コードレビューの目的
- PRを小さく保つための考え方
- きれいなコミット履歴の作り方
をまとめています。
想定している読者は、
- コードレビューの目的を改めて整理したい方
- 「PRって、どのくらいの大きさで出すべき？」と迷っている方
- レビュワーとして、どこを見ればいいか曖昧に感じている方
です。
【このテーマを選んだ背景】
👀背景1：自分のPRの出し方を見直したかった
きっかけは、こちらのショート動画を見たことです。
「PRの数を評価基準にする」という考え方は、やや極端かもしれません（プログラミングスクールの先輩にこの動画を見せたところ、そういった反応もありました）。
ただ、「では自分の今のPRの出し方は適切なのか？」 という疑問が生まれたのは確かで、自分は大きめのPRを1本ドンっと出すことが多い。これはレビュワーの負担を確実に上げているはずで、整理する良い機会だと感じました。
👀背景2：レビュー担当時の観点が曖昧だった
最近、レビューを担当する機会が増えてきました。しかし、いざ着手してみると「なんとなく気になった箇所」にコメントして終わる、というパターンになりがち。
「自分はレビューで何を見るべきなのか」を言語化できていないと、レビューを後回しにしてしまう原因になります。今後レビュー機会がさらに増えることを考えると、この状態は早めに改善したいと感じていました。
【コードレビューの目的】
今回の輪読会では、まずこちらのZenn記事を参考にしました。
👀コードレビューには、大きく4つの目的がある
◎1. 品質保証
バグの早期発見・セキュリティ上の懸念・パフォーマンス上の問題の確認が目的です。
達成するには、レビュワー側の技術力と対象領域への理解が必要になります。
◎2. ナレッジ共有
レビュワーとレビュイーが互いの得意分野を活かし、スキル向上と品質向上につなげることが目的です。「なぜこの実装にしたか」「別案はあるか」といったコミュニケーションが鍵になります。
◎3. チーム連携・標準化
コーディング規約や設計方針と整合しているかを確認することが目的です。規約・方針を参照しながらレビューすることが必要です。
◎4. 保守性向上
他メンバーによる保守や追加開発を前提に、技術的負債を増やさないことが目的です。可読性や再利用性に焦点を当ててレビューします。
👀整理してみた所感
- （自戒） コーディング規約をAIに任せてしまっていることが多く、自分でも改めて理解を深めなければと感じました。
- PRが大きくなるほど、上記4つの観点すべてを満たしたレビューをするのが難しくなる。「PRを小さく保つ」ことの重要性は、レビュー目的の観点からも裏付けられると思います。
【実装者ができること：PRを小さくする】
参考にした記事はこちらです。
👀なぜ大きいPRは問題と言われるのか
レビュー依頼が届いたとき、PRが大きく複雑に見えると「後でまとめて見よう」となりやすいです。その結果、
- 詳細確認が不十分なまま承認され、技術的負債が増える
- レビューが遅れ、リリースが遅れ、機会損失につながる
といった問題が起きます。これは、レビュワーが悪いわけではなく、PRの作り方に原因があります。
👀「10分ルール」と「1PR1コンテキスト」
上記を踏まえた、PRを小さくするための基本的な考え方は次の2つです。
① 10分ルール
「レビューが10分以内で終わるサイズ」を目標にする。
② 1PR1コンテキスト
1つのPRには、1つの関心ごとだけを含める。
悪い例：
- ログイン機能の改善 ＋ UI調整 ＋ バグ修正（が混在している）
良い例：
- PR①：ログイン機能のバリデーション強化
- PR②：ログイン画面のレイアウト調整
- PR③：○○画面の表示バグ修正
👀PRの質を上げる工夫
コードの差分だけでなく、「どのように動作確認し、何を確認したか」 を残しておくことも大切です。実際のUIのスクリーンショットや、動作確認の手順などをPR説明に添えると、レビュワーが確認しやすくなります。
【きれいなコミット履歴の作り方】
参考にした記事はこちらです。
👀きれいなPRは、きれいなコミット履歴から作られる
大前提として、1つのPRは1つの関心ごと・目的のみを扱うべきです。
そして、きれいなPRとは、その目的を達成するまでの意思決定が適切に積み上がった結果として成立しているものです。
差分だけでは読み取れない「なぜその変更をしたのか」を、コミットの分割とコミットメッセージで説明できると、レビュワーがコードを理解しやすくなります。
👀きれいなコミット履歴の例
例として、「フォームが送信されないバグを修正する」という目的のPRを考えてみます。
fix: フォームが送信されないバグを修正する ← このPRの目的
1. debug: 原因特定のためのデバッグログを追加
2. fix: 特定した原因に対する修正を適用
3. chore: デバッグログを削除
4. style: フォーマット調整
このように意思決定の順序が追える粒度でコミットを切ると、PRを見た人に「なぜこの変更が必要だったのか」が伝わりやすくなります。
👀コミットメッセージにプレフィックスを付ける
コミットの種類をプレフィックスで分類すると、コミット履歴が一覧で見やすくなります。
| 旧 | 新 |
|---|---|
#1830 UI修正 |
fix: #1830 UI修正 |
#1831 ○○の改修 |
ref: #1831 ○○のリファクタリング |
このプレフィックス運用には Conventional Commits が参考になります。
【今後の方針】
輪読会を通じて整理した、自分たちのチームへの今後のアクションです。
- 10分ルール・1PR1コンテキストを徹底する
- PRテンプレートを運用する（BitbucketにはPRテンプレート保存機能がある）
# 目的
-
# 変更点（箇条書き）
-
-
# その他
- 影響範囲：
- リリース注意点：
- スクリーンショット（UI変更あれば）
- コミットメッセージ規約を整備する（Conventional Commitsを参考に、チーム内で統一する）
- （自戒）コーディング規約をちゃんと読む
【おわりに】
「PRをなるべく小さくする」「1PR1コンテキスト」という考え方は、聞いたことがある方も多いと思います。ただ、なぜそれが大事なのかをコードレビューの目的から紐解いて整理できたのは、今回の輪読会の大きな収穫でした。
実装・レビュー・リリースの流れが整うと、チーム全体の開発体験が向上します。小さな工夫の積み重ねを大切にしていきたいと思います🔥