「伝わる」GitHub PRと「育てる」レビューコメントの書き方

こんにちは！Mobile Growthの朴（パク）です。

5月1日からWantedlyへ入社し、AndroidをメインにWantedlyアプリの開発を担当しています。

チームにジョインしてまだ2ヶ月ほどですが、日々の業務の中でプルリクエスト (PR) 作成やレビューの進め方について「丁寧で分かりやすい」と好評でしたので、いくつか実践していることや意識していることについて紹介したいと思います。

はじめに

エンジニアの皆さん、開発において適切なPR作成とレビューは実践できていますか？

多くのエンジニアが日々バージョン管理システムを使い、チームのコードやプロジェクトを管理していると思われます。Wantedlyでは、エンジニアだけでなくビジネスサイドも含め、コードやプロジェクト、ドキュメント管理をGitHub上で運用しています。

このようにチーム開発を円滑に進めるために、本記事ではGitHubのPRとレビューコメントに焦点を当て、「伝わるPR」と「育てるレビュー」を通じて、チーム開発の生産性と技術力を向上させる具体的な方法をご紹介します。多くの方が抱える共通の課題に対する一助となれば幸いです。

序論：AI時代に人間が介在する価値

AIの進化により、コード生成やレビューの補助が加速する現代において、人間が介在する価値はどこにあるのでしょうか？

AIによるコード生成やレビュー補助、自動化が進む中で、開発において人間が果たす役割はさらに重要になっていると考えています。

人間はAIには難しい、変更の背景にある意図や設計判断の共有ができます。また、多くの人にコードをレビューして貰うことで責任分散や品質担保ができます。さらに、レビューを依頼する側もレビューする側も知識共有の場として活用でき、チームの成長を催促し、様々な議論を通じて「判断力」と「選定力」が強化されます。

本論：『伝わるPR』と『育てるレビュー』

ここからは具体的な例を用いながら『伝わるPR』を作成する方法と『育てるレビュー』を行う方法について説明します。

『伝わるPR』を作成する

テンプレートの活用

まず、PR作成前にチームや個人で使っているテンプレートがないか確認し、それに従いましょう。もしなければ、インターネット上にあるテンプレートの例文などを参考にしてみるか、AIに土台を作成するように依頼し、チームや自分に合った形式にカスタマイズしていくことをお勧めします。

なぜテンプレートが重要かというと、情報の一貫性が保たれ、今後「どう書いたらいいのか」の迷いがなくなり、PRを作成しながら自分の中で目的と対応内容を再構築できるからです。これにより、抜け漏れ防止や「本当にこの対応で良いか」を再認識できます。

構成と書き方

以下は、私がよく使っているPR構成と例文です。

- Why（なぜその変更が必要か）：背景や目的を明確化
- What（何を変更したか）：変更内容と影響範囲
- Evidence（根拠、結果）：テスト方法/結果、スクリーンショット、動画
- Checklist（確認事項）：セルフレビュー
- Others（その他補足事項）：考慮事項、議論したい点

可能な限り、読み手を意識して作成することがポイントです。

「読み手がどのような情報を求めているかよく分からない」という方は、未来の自分が「何をしてたのか」を完全に忘れている状態で、PRのみで「なぜ」この変更をすることになり、「何を」して、「どれぐらいの範囲を、どのような手順で」確認したら嬉しいのか、またこの変更対応で「何を思って、どういう困難があったのか」などを書いて行くのが、私の中での「良いPR」、「伝わるPR」だと考えています。

『育てるレビュー』を行う

ここからは「育てるレビュー」とは何かについて紹介します。

コメントの「意図」を明確にするラベル付け / 優先順位付け

まずは、PR作成同様にコメントにもテンプレート的なものがあれば良いです。チームで決めるのも良いですし、個人的にラベルをつけて優先順位やどのような意味で使用しているかをチームやレビュイーと共有しておくと、更にレビューと開発がスムーズになります。

以下のように、私が初めてレビューする人にはラベルと優先順位、マージまでの基準を案内しています。

- Must（必須対応）
- Should（強く推奨）
- IMO/IMHO（意見・提案）
- Optional（任意）
- Nitpick（ごく軽微な指摘）

ラベルを使ってレビューされる方は他にも多くいらっしゃると思いますが、レビューされる側としてはちょっとしたアイデアや優先度が低いものでも全部対応しようとすることもあります。開発する上で全部を完璧にしようとすると時間に追われる場合や、「どこまで対応したらいいんだろう？」と悩む時でも、必須項目さえ対応すれば良いという安心感につながります。これにより、レビューされる側に判断を委ねる機会が生まれ、「判断力」と「選定力」を養うことにも繋がります。

レビュー観点

ここからはコードレビューする上でいくつかのレビュー観点を紹介します。

- 機能要件・ユーザー体験の確認
- チームルール/公式ドキュメント/ガイドラインとの整合性
- コードの可読性と保守性
- 潜在的な問題の発見

第一に、機能要件・ユーザー体験の確認をします。適切なPR文を書いていればコードはまず見ずとも、PR文だけで判断できるはずです。自分が同じ対応をするとなったら、どのように実装していたかを軽くイメージすると良いでしょう。

その後、コードの変更分を確認します。コードがチームで決めたルールに沿って書かれてるか、または公式ドキュメントやガイドラインとの整合性が取れているかをみます。ルールに従わず各自好きなように書いてしまっては、統一性がなくなり、後々不具合に遭遇した場合や機能拡張などで他の人が同じ箇所を変更する時、コードと仕様を把握するのに時間的コストが発生するからです。公式ドキュメントやガイドラインに沿っていると、新規参入者が増えた場合でも学習コストが下がります。

ドキュメントやガイドラインにない部分は、一見してコードの可読性が優れているか、今後のための調整や保守性に問題ないかを確認します。この時点で、「私だったらこう書きます」や「調べたらこんな関数や機能がありましたので、今後活用してみてください！」と意見交換のコメントができます。

最後は、少し経験によるものではありますが、以前似たようなコードを書いていたりすると、関連した箇所で不具合や同じ指摘を受けることがあるため、「~~みたいな問題になる可能性はないですか？」、「~~を変更しているため、~~も問題ないか確認しておいた方が良さそうです」といった経験による潜在的な問題を共有し、発見につながるケースもあります。

Suggestion機能の活用

最後に、レビュー時Suggestion機能を積極的に活用することをおすすめします。

言葉で曖昧に説明するより、コードで直接記述した方がレビュイーも分かりやすく、提案が受け入れられるケースも多くなります。