この記事は Liz Kammer (Google), Maggie Hodges (UX research consultant), Ambar Murillo (Google) による Google Testing Blog の記事 "Code Health: Respectful Reviews == Useful Reviews" を元に翻訳・加筆したものです。詳しくは元記事をご覧ください。

 本投稿は、コードの健全性シリーズの 1 つです。Google Testing on the Toilet（トイレでのテスト）として世界中の Google のトイレに登場したエピソードが元になっています。オフィスに掲示できる印刷用のバージョンもダウンロードできます。

投稿者: Liz Kammer（Google）、Maggie Hodges（UX リサーチ コンサルタント）、Ambar Murillo（Google）


コードレビューはソフトウェア プロジェクトの品質を改善するための貴重なツールと認識されていますが、コードレビューのコメントが不明確だったりきつい表現だったりすると、好ましくない結果が生まれる場合があります。たとえば、レビューが遅れたり、関連するコードレビューが進まなくなったり、否定的な感情が生まれたり、他の貢献者や同僚に対する否定的な印象ができたりすることがあります。

以下のポイントを参考に、コードレビューのコメントを礼儀正しく解決することをこころがけましょう。

レビュアーまたは作成者として:

  • 推奨: 相手の能力を推測する。作成者の実装やレビュアーの推奨事項は、皆さんとは違う状況で行われたものかもしれません。まずは質問して理解しようとするところから始めましょう。
  • 推奨: 根拠や背景を示す。たとえば、ベスト プラクティスに関するドキュメント、スタイルガイド、設計ドキュメントなどがこれにあたります。他のユーザーが皆さんの判断について理解したり、助言したりするうえで役立つことがあります。 
  • 推奨: コメントがどのように解釈されるかを考える。誇張、ジョーク、絵文字などは、意図したとおりに解釈されない可能性があることに注意します。
    Author Don’t:
I prefer short names so I’d rather
    not change this. Unless you make
    me? :)

    

    

    訳: 短い名前のほうが好きなので変更したく
    

    ないです。あなたが私の考えを変えられる
    

    なら話は別ですが :)
    
    		
 
    Author Do:
Best practice suggests omitting
    

    obvious/generic terms. I’m not
    

    sure how to reconcile that
    

    advice with this request.
    

    

    

    訳: ベストプラクティスでは自明あるいは
    

    一般的な名称は省略することとなっています。
    

    このコード変更においてそれをどう適用する
    

    かはまだわかっていません。
    
    		
 
    

    

    

    • 

  • 非推奨: 人を批判する。人ではなく、コードについての見解を述べます。コメントに人を指す表現（例:「あなた」や「あなたの」）が含まれているだけでも、コードを改善するという目的の妨げになることがあります。

    

    

    Reviewer Don’t:
Why are you using this approach?
    

    You’re adding unnecessary
    

    complexity.

    

    

    

    訳: なぜこのような手法を採用したのでしょう。
    

    不必要に複雑にしようとしています。
    

    Reviewer Do:
This concurrency model appears to
    

    be adding complexity to the
    

    system without any visible
    

    performance benefit.
    

    

    

    訳: この並行モデルは目に見えた性能改善を
    

    特にもたらすわけでもなくシステムをより複雑に
    

    しているように思えます。
    

    

    

    

    • 

  • 非推奨: きつい言葉を使う。否定的な調子になっているコードレビューのコメントは、有用性が低下する傾向にあります。たとえば以前の研究によると、作成者が非常に否定的なコメントを有用だと感じる確率は 57% ですが、中立的なコメントを有用だと感じる確率は 79% でした。 
    • 




レビュアーとして:




    

  • 推奨: 具体的で実現可能なフィードバックを提供する。具体的なアドバイスがない場合は、作成者がその決定を下した理由について尋ねるのもよいでしょう。
    

    
 

    
 
    Reviewer Don’t:
I don’t understand this.

    

    

    訳: 意味がわかりません
    
    		
 
    Reviewer Do:
If this is an optimization, can you
    

    please add comments?
    

    

    訳: ここのコードが最適化のためのものなら
    

    その旨コメントを追加してください。
    
    		
 
    

    

    

    • 

  • 
推奨: あまりに細かいことや必要性が低いコメントは、明確に区別できるようにする。たとえば、「Nit」（些細な指摘）や「Optional」（省略可能）などの印をつけます。これにより、作成者がレビュアーの意図をはっきりと理解できるようになります。
    • 










作成者として:








    

  • 推奨: フィードバックを受けたら、コードについて明確に説明する、またはレビュアーのコメントに回答する。そうしないと、フィードバックを受けてコードの改善を行う能力に欠けると見なされる可能性があります。
    

    
 

    
 
    Author Don’t:
That makes sense in some cases but
    

    not here.

    

    

    訳: フィードバックの内容があてはまる場合
    

    もありますが、今回は違うと思います。
    
    		
 
    Author Do:
I added a comment about why
    

    it’s implemented that way.
    

    

    訳: なぜこのように実装したかコメントを
    

    追加しました。
    
    		
 
    

    

    

    • 

  • 
推奨: フィードバックに賛同できない場合は、自分のアプローチの利点を説明します。それでも合意が得られない場合は、コードレビューにおける不一致を解消するための Google のガイダンスに従います。
    • 








Reviewed by Yoshifumi Yamaguchi - Developer Relations Team