レビュアーのための禁断リスト～これだけはやってはいけない！～ / 開発者向けブログ・イベント

この記事は GMOインターネットグループ Advent Calendar 2024 7日目の記事です。

はじめに

レビューは、ソフトウェア開発やあらゆるフェーズにおいて欠かせないプロセスです。しかし、適切に行わなければ逆効果にもなり得るため、注意すべき点は多岐にわたります。本記事では、「絶対に避けるべきこと」をテーマに、特にソースコードレビューに焦点を当てつつ、その他の成果物レビューにおいても共通する失敗例とその影響、そして回避方法を詳しく解説します。

特に若手社員へのフィードバックでは、指導的な立場を保ちつつ、どのようにして建設的な意見を提供するかが重要です。この記事を通じて、効率的で効果的なレビューの実践方法の参考にいただければ幸いです。

言葉選びの極意！レビューで使ってはいけないフレーズ

この章では、レビュー中の「言葉遣い」に焦点を当て、どのようなフレーズが受け手に悪影響を与えるか、そしてその代替となる表現を具体的に解説します。レビューはコミュニケーションの場であり、言葉選び一つで相手のモチベーションや受け止め方が大きく変わります。以下に、不適切なフレーズとその改善例を挙げます。

こんなの基本的なことです

このフレーズは、相手の知識やスキルを軽視している印象を与え、成長意欲を削ぐ可能性があります。代わりに、「この点については、ベストプラクティスとして○○という手法もあります。参考にしてみてください。」といった表現を使うことで、指摘を学びの機会として提供でき、相手も提案を素直に受け入れやすくなります。

これって意味がありますか？

この言い回しでは、相手の努力を否定していると捉えられる危険性があります。相手の意図を確認し、建設的なフィードバックを行うためにも、より配慮した表現を用いましょう。例えば、「この部分の意図をもう少し詳しく説明してもらえますか？もしかすると、もっと効果的な方法が見つかるかもしれません」と提案することで、互いの理解を深めながら、最適な解決策を探求することができます。

前にも同じミスをしています

何度も同じミスをすることは、レビュアーとしては見逃せません。ただし、単にミスを指摘するのではなく、「以前も同じ指摘をしたかと思いますが、まだ課題が残っているようです。この部分の改善を定着させるために、例えばチェックリストを作るなど、具体的な行動計画を立ててみませんか？」と、過去の間違いを指摘すると共に、改善のための協力を促すことで、前向きな改善活動へと導きます。

このコードを書いたのは誰ですか？

複数人での会議中に「犯人捜し」のような発言は、チームの信頼関係や安心感を損ねることがあります。問題が発生した場合は、責任を個人に求めるのではなく、根本的な解決に向けてチーム全体でのアプローチが重要です。ミスは個人の責任だけでなく、チームのプロセスやリーダーシップの問題が原因であることも考慮に入れ、チーム全体でのプロセスの見直しを促すことが、将来的により健全なチーム運営につながります。また、個別指導が必要な場合は、プライベートな1on1の場を設けることで適切に対応しましょう。

他の誰かにやってもらった方が早いです

単に効率性を追求するだけのコメントは、相手の才能や努力を軽視していると受け取られ、モチベーションを低下させることがあります。このような状況で有効なアプローチは、チームの協力とスキルの共有を促すことです。例えば、「このタスクは特定のスキルセットを必要とします。チーム内で適切なサポートとスキルシェアが必要ですので、協力を仰いで効率的に進めていきましょう。」と表現することで、チーム全体の連帯感を高め、効果的なタスク遂行を促進できます。

それはタブー！レビューで触れてはいけないトピック

この章では、「レビューに不適切な話題」に焦点を当て、その理解を深めます。レビューの本来の目的は成果物の品質向上であり、個人に対する非難や、コーディング規約に違反しない個人的なスタイルの押し付けは避けるべきです。以下に、レビューの際に避けるべきトピックの具体例を示します。

個人的な好みの押し付け

個人的な好みを押し付ける指摘は、客観性に欠け、レビュアーの自己満足で終わる場合が多いです。このような指摘を受けたレビューイは、具体的な改善点が見えず、「どうすればいいのか？」と戸惑い、作業の進行が滞ってしまうことがあります。より建設的なアプローチとしては、個人の感覚ではなく、チームが定めたコーディング規約や一般的な業界標準（ベストプラクティス）を参照し、それに基づいた客観的な理由を示しましょう。

個人攻撃

個人を批判する言葉、特に性格や人格、能力に対する否定的な発言は、相手のモチベーションを著しく損なうだけでなく、心理的な不安感を与える可能性があります。例えば、「どうしてそんなに遅いんだ」や「君はいつもミスばかりだ」といった性格や行動パターンを非難する言動は、相手の自己肯定感を傷つけるだけでなく、チーム全体の信頼関係をも崩す要因となります。パワハラを伴う言動は以ての外です。

問題点を指摘する際は、個人の特性や性格ではなく、具体的な事実や成果物そのものに焦点を当てて、建設的な指摘や対話を心がけることが重要です。

曖昧な指摘

曖昧な指摘は、受け手にとって具体性がなく、どの部分をどう修正すれば良いのか分かりません。この結果、確認作業が増え、レビュープロセス全体の効率が下がります。レビュアーは詳細なリンクや説明を提供し、どのように改善できるか明確なガイドラインを与えましょう。これにより、レビューのプロセスがスムーズに進み、時間の節約にも繋がります。

根拠のない否定

根拠のない否定は議論を停滞させ、相手に無力感を与えることがあります。これにより、何をどう改善すればよいのかが不明瞭となり、レビューの効果が低下します。レビューでは、具体的な問題点を明らかにし、それを改善するための明確な理由と具体的な提案を伴うことが重要です。改善することで、有意義なフィードバックが行われ、解決策に向けた建設的な議論が促進されます。

ちょっと待って！それだと時間無駄にしてるかも

レビューは、効率よく、建設的に進めることが求められます。しかし、いくつかの習慣や方法が、知らず知らずのうちに時間の無駄を生み出しているかもしれません。この章では、レビューにおける「時間を無駄にする原因」と「その解決方法」を具体的に解説します。

レビューの確認観点を用意しない

ソースコードレビューを行う際、コーディング規約や設計書が用意されていることは多いですが、レビューの確認観点が整備されていないケースも少なくありません。この場合、レビュアーが指摘する内容に一貫性がなくなり、場当たり的なコメントが増えてしまいます。結果として、必要な指摘が漏れたり、レビューイが曖昧な指摘に混乱して時間を浪費したりする可能性があります。

特に、業務特有の実装ルールがある場合には注意が必要です。例えば、ポリモーフィズムの使用方法や継承のルールといった抽象的な要件は、明文化されていないと漏れがちです。これを防ぐためには、レビューのチェックリストを事前に用意し、全員が共有することが有効です。こうしたリストは、NotionやConfluenceなどのツールを活用して管理することで、誰でも簡単に確認できる状態を整えられます。確認観点を明確にすることで、指摘の質を向上させるだけでなく、レビュープロセス全体の効率化にも繋がります。

「指摘したので修正お願いします。」とチャットでやりとり

レビューにおいて、コミットIDやプルリクエストのリンクをチャットでやり取りするのは一見手軽に思えます。しかし、相手がすぐに返信や対応をしない場合、非同期のやり取りが何度も発生し、結果として時間を浪費してしまうことがあります。さらに、レビュアー側にも「自分の依頼が伝わったのか確認する手間」が生まれ、双方の生産性が低下します。

このような問題を解決するために、プロジェクトで使用しているバージョン管理システムやレビューツールの通知機能を活用するのがおすすめです。例えば、GitHubやGitLabにはレビュー依頼やコメントを自動通知する仕組みがあります。これにより、レビュアーが個別に連絡を取る必要がなくなり、レビューの進捗を確認する手間も大幅に削減されます。さらに、GitHubのプルリクエストタブを利用すれば、リポジトリをまたいでレビュー待ちのタスクを一覧で確認できるため、レビュアー自身のタスク管理も効率化されます。

このように、ツールを活用してレビューのやり取りをツール内で完結させることで、チャットによるやり取りの煩雑さから解放され、レビュー効率を飛躍的に向上させることが可能です。

ここの45行目を修正よろしく。画像ペタ。

レビューの中で、行番号やスクリーンショットを添付して修正箇所を指摘する場面があるかもしれません。しかし、この方法は受け手が該当箇所を正確に特定するのに余計な時間を要する場合があります。また、コードが更新された際に行番号が変わることで、コメントが無意味になるリスクもあります。その結果、レビューイが必要以上に修正箇所を探し回る時間を生むことになります。

この問題を解決するためには、コードレビューシステムの機能を最大限に活用することが大切です。GitHubやGitLabでは、特定の行に直接コメントを追加することが可能であり、レビューイはその箇所に即座にアクセスできます。また、該当部分に関連するリンクを共有することで、コード全体の流れを理解した上で指摘を確認してもらうことができます。例えば、「このメソッドの非同期処理化でパフォーマンスが向上する可能性があります。具体的にはこの箇所です。」といった具体的な説明を加えれば、レビューイはより効率的に修正作業を進められるでしょう。

適切な指摘方法を用いることで、受け手が最小限の手間で修正箇所を把握でき、コミュニケーションの齟齬を防ぐことができます。レビュアーにとっても、正確かつ建設的な指摘を行う習慣がつくため、全体的なレビュー効率が向上します。

ちょっと待って！そのリファクタリング指摘大丈夫？

リファクタリングは、コードをより良くするための重要な取り組みですが、慎重に行わなければ、かえって保守性やプロジェクト全体の効率を損ねることがあります。この章では、リファクタリング指摘における注意点を詳しく解説します。

冗長的なロジックだ！リファクタリング！

冗長なロジックを見つけると、すぐに「共通化」や「簡潔化」を提案したくなるかもしれません。しかし、業務要件や設計意図に基づき、あえて冗長性を残しているケースもあります。このような設計上の冗長性を無視して指摘を行うと、後々の保守や拡張が困難になることがあります。たとえば、似たような処理でも、異なるモジュールや機能で将来的に分岐が生じることを見越している場合があります。

冗長なロジックのリファクタリングを提案する際は、将来的な利用方法を考慮し、共通化が新たな問題を生むリスクがないか慎重に検討する必要があります。

ここも念のためリファクタリングしてください。あとここも念のため。。。

リファクタリングが重要であることは間違いありませんが、すべてのコードに対してリファクタリングを行うのは現実的ではありません。特に、変更頻度が低いコードや影響範囲が限定的なコードに対して過剰なリファクタリングを行うと、プロジェクト全体の進捗に悪影響を与えることがあります。

リファクタリング指摘を行う際には、そのコードの変更頻度や今後のメンテナンス性を考慮する必要があります。もしリファクタリングが必要だとしても、「この変更がどのくらいの価値を生むのか」「その効果がプロジェクト全体に対して適切なコストで実現できるか」を評価することが大切です。むやみに「念のため」という理由でリファクタリングを提案するのではなく、具体的な改善効果がある箇所に絞り込むべきです。

テストコードは正常に通ってるし問題ないですね。多分。

テストコードが正常に動作していることはもちろん重要ですが、それだけで十分とは言えません。テストコードはプロダクトコードと同じように、チームにとっての資産です。特に大規模なシステムでは、テストコードの質がプロジェクト全体の信頼性に直結します。

テストコードをレビューする際は、単に「通ればよい」と考えず、次の点を確認してください。テストケースが十分に網羅されているか、意図が明確か、保守性が高いかどうかです。レビューの機会は貴重であり、プロダクトコードとテストコードを分けて考えるのではなく、一貫して高い品質を目指すべきです。

このリファクタリングは全クラスに横展開をお願いします。

リファクタリングの範囲が広すぎると、影響範囲が大きくなり、予期せぬ問題が発生するリスクが高まります。また、もし影響が発生した場合に、それを元に戻す作業が非常に複雑になる可能性があります。全クラスへの横展開を提案する場合には、実施する前に、影響範囲の特定やリスク評価を行うことが不可欠です。

特に大規模なリファクタリングの場合は、別のタスクやブランチとして分けて進めることを推奨します。これにより、問題が発生した際にも、迅速に元の状態に戻すことが可能になります。また、横展開する前に、限定的な範囲でリファクタリングを試し、結果を評価してから進めることで、プロジェクト全体への影響を最小限に抑えられます。

レビュアー３つの心得

ここまでお読みいただきありがとうございます。この記事では、レビュアーとして注意すべき言動や、より良いレビューのためのポイントを解説してきました。次に、レビュー現場で役立つ『レビュアー3つの心得』をお伝えします。これらを実践することで、建設的で価値あるレビューが実現できるはずです。

具体性を重視する

曖昧な指摘や「良くない」「修正が必要」の一言だけでは、指摘を受けた人にとって次に何をすべきかが分からず、フラストレーションを生む原因となります。
具体的な改善案や参考コードを提示することで、相手が行動に移しやすくなります。例えば、次のような比較を考えてみてください。

NG：「この表現は良くないと思います。」
OK：「○○という表現は広すぎて意図が伝わりにくいので、△△のように具体的にすると良いと思います。」

レビューは問題を指摘するだけではなく、解決への道筋を示すガイドであるべきです。具体的な例を挙げることで、レビューの価値を何倍にも高められます。

ポジティブな表現を心がける

レビューは建設的な議論の場であるべきです。攻撃的な言葉や否定的なトーンは避け、提案型の表現でレビューすることを努めましょう。どんな指摘でも、受け手が「次はもっと良いコードを書こう」「もっと良い設計書を書こう」と前向きに感じられるかが重要です。

たとえば、次のような改善が考えられます。

NG：「こんな内容じゃダメです。」
OK：「この部分が少し複雑になっているので、こう分けるとシンプルになるかもしれません。」

「ここは面白いアプローチですね」「こうするとさらに良くなりそうです」といった肯定的なコメントを織り交ぜると、相手のモチベーションが維持されるだけでなく、チーム全体の雰囲気も良くなります。

相手の意図を尊重する

レビューでは、自分の視点だけでなく、相手の背景や意図を理解しようとする姿勢が不可欠です。自分の考えを押し付けるのではなく、質問形式で改善案を提示することで、議論を建設的に進められます。

NG：「こうするのが正しい。直してください。」
OK：「こちらは、○○という意図でしょうか？もしそうなら、この方法も検討できるかもしれません。」

また、時には意図を深掘りすることで、新たな視点が生まれることもあります。「なぜこの方法を選んだのか？」と問うことで、指摘を受ける人の工夫や前提条件を尊重しつつ、最適なアプローチを一緒に探ることができます。

レビュー改革のステップ！チーム全体で質を高める方法

この記事では、「レビュアーが絶対にやってはいけないこと」を中心に解説してきましたが、最後に、レビューをチーム全体で質を高めるための具体的なステップを紹介します。禁断リストを反面教師とするだけでなく、実際の改善につながるヒントを通じて、レビューがチームの品質向上に貢献する取り組みとなるよう、プロセスやルールの明確化と一貫性の重要性を解説します。

Gitのコミットの粒度はコミットコメント一言で伝わる範囲

コミットには、作業内容が明確に分かる粒度でまとめることが重要です。複数の修正や変更をひとつのコミットにまとめてしまうと、後にコードを追跡する際に困難が生じます。たとえば、ひとつのコミットに「バグ修正」「機能追加」「リファクタリング」が混在していると、どの変更がどの影響を与えたのかを判断するのに余計な時間がかかってしまいます。

この問題を防ぐには、コミットの粒度を「コミットコメント一言で説明できる範囲」に収めることを徹底しましょう。さらに、コミットメッセージには、関連するタスクやissue IDを明記するルールを設けると良いでしょう。たとえば、「fix[#123]:○○に関するバグを修正」や「feat[#456]:○○の新機能追加」といった形式で記述することで、作業の目的と内容がすぐに把握できるようになります。コミットの粒度を適切に保つことは、レビュー効率の向上だけでなく、将来的なコードの保守性にも寄与します。

レビューの粒度はタスク単位

レビューの対象範囲が広すぎると、レビュアーが見逃しを起こしやすくなり、指摘の質が低下します。一方、タスクをまたぐようなレビューは、何をどこまで確認すべきか曖昧になりがちです。その結果、細かな問題が見落とされるだけでなく、レビュアーの負担が増し、全体的な効率が下がってしまいます。

理想的なレビューの単位は、タスクやチケットごとに収めることです。バグ修正や機能追加といった具体的なタスク単位でレビューを行うことで、レビュアーが集中して内容を確認でき、フィードバックの質が向上します。さらに、タスク外の修正（「ついでにこれも直した」など）を避けることで、レビュープロセスがシンプルで明確になります。このルールを徹底することが、レビュー全体の透明性を高める第一歩です。

定期的なプロセス評価

コードレビューは、一律に決まったものではなく、チームやプロジェクトの状況に応じて柔軟に見直す必要があります。定期的にレビューの現状を振り返り、問題点や改善点を明らかにすることで、より効果的な方法へと進化させることができます。

見直しの際は、レビュー観点やレビュアー体制の再構築を含む議論を行うと良いでしょう。たとえば、レビュー観点が適切か、無駄な指摘が多すぎないか、あるいはレビュアーの負担が偏り過ぎていないかといった具体的な課題を洗い出します。また、ツールの活用状況や通知機能の効果を定期的に確認し、効率化の可能性を模索することも重要です。

このプロセスでは、単にレビュアーや開発者の意見を聞くだけでなく、レビュー時間、指摘件数、修正回数といった定量的なデータを活用することで、客観性と信頼性を高めることができます。定期的な改善を重ねることで、レビューはチームの成長を支える仕組みとなります。

こうした取り組みを継続することで、レビューは単なるフィードバックの場にとどまらず、チームのスキル向上やプロジェクトの品質向上に直結する重要なプロセスへと発展していくでしょう。

おわりに

この記事を通じて、レビューにおいて避けるべき具体的な行動や、その背後にある理由についてご理解いただけたことと思います。コードレビューは、AIを活用することで一部のプロセスを自動化し効率化することも可能です。しかし、業務要件の深い理解やプロジェクト固有の実装ルールへの適応は、依然として人間のレビュアーが担うべき重要な役割です。

特に、細部における判断や提案は、技術的な洞察と人間ならではの視点が不可欠です。そのため、AIの力を活用しつつも、人間のレビューによる補完と相互作用が求められます。本記事を通じて、皆さまのレビューがより効果的かつ建設的なものとなり、プロジェクト全体の品質向上に寄与する一助となれば幸いです。