Guidelines for a healthy code review culture/ja

コード レビューは感情の労働です. 私たちは、自分が書いたコードに至るまで、この仕事に感情移入している存在なのです. フィードバックを与えたり受け取ったりするのは大変なことで、健全なコード レビュー文化を構築するためには、この負荷を全員で共有する必要があります.

コード レビューは、表面的には、物事が壊れるのを防ぎ、コードの健全性を維持するためのものです. 実際には、それ以上のもの (のはず) です.



コードレビューの目標

 * 1) 不具合や脆弱性が本番環境のコードに反映されるのを防ぐために協力し合うこと
 * 2) 保守性を促進し、将来の不満や混乱を防止すること
 * 3) 協力者が学び、成長するための教育の機会を提供し、新しい協力者を呼び込むこと
 * 4) 協調作業を通じてコードの共有理解、オーナーシップ、説明責任を育み、より機能的で充実した貢献者チームを実現すること

最終的に、コード レビューは対話であり、私たちの仕事のほとんどは遠隔地や非同期で行われるため、この運動にとって特に重要なものです. 私たちは、コード レビュアーのコミュニティの一員であり、このコミュニティ内で信頼関係を構築することが、コードレビューの目標を達成し、既存のコミュニティ メンバーをサポートし、新しいメンバーを導入するために役立つと考えています.



健全なコード レビュー文化とは?
"健全なコードレビュー文化とは、恐れることなくフィードバックを歓迎するものです."

これを詳しく見てみましょう:


 * フィードバックは歓迎される: 健全なコードレビュー文化では、フィードバックを受け取ることは、本番環境に進む前に問題点が発見され、知識が共有され、人々が協力してコードを改善することを意味します. このような文化で作業することには、やりがいがあります.
 * 恐れなく: 心理的安全性は、健全なコードレビュー文化の基盤です. $1 人々はフィードバックを提供したり受け取ったりするために、快適な気持ちでいる必要があります. パッチを提出したり、批判を行ったりすることは、圧迫感を感じることがあり、このプロセスには信頼が必要です. 安全な環境にいる人たちは、新しいアイデアを提案したり、実験したり、成長したりできます. 安全を感じない人たちは、やがて貢献を止めて去っていってしまいます. People need to feel comfortable providing and receiving feedback. Submitting a patch or providing criticism can be intimidating, and this process requires trust. People who feel safe are more able to propose new ideas, experiment, and grow. People who don’t feel safe will eventually stop contributing and leave.

私たちは、自分たちの価値観を定義し、それを作業の中で適用することで、このような文化を作り出せます.



健全なコードレビュー文化の価値観


エゴよりも尊重と共感

 * 私たちのコードが私たちを定義しないこと: 私たちは書いたコードに深く関わっていますが、コーディングは私たちがやることであり、誰であるかではありません. コーダーではなくコードを批評しましょう.
 * 思いやりをもって先導する: まず自分から始め、それを誰にでも広げましょう. 私たちは皆今できる最善を尽くしています.
 * 信頼を築く: 優しさ、共感、好奇心が共同作業者間の関係を築けます. 信頼は心理的安全性につながり、素晴らしい作業と幸せな貢献者につながります.
 * 能力を想定する: 無能力を想定するのではなく、質問しましょう. 何かを誤解しているかもしれないのはあなたかもしれません.
 * 権力構造に気を配る: あなたよりも経験が少ない人の意見に耳を傾けましょう. 声の小さい人たちを支援しましょう. 他の人に譲りましょう.



競争よりも協力

 * 協力に重点を置くこと: 協力に注力すると、エゴが邪魔をすることはありません. 協力は、多くの人々が貢献することを可能にし、より良い製品を生み出します.
 * 協力の課題を認識する: 私たちの中には、トーンを管理するのが難しい人、好きではない解決策に譲ることに苦労する人、批判的であることを避ける人もいます. みんな違うけど、成長できるんだということを覚えておいてください.
 * フィードバックを贈り物として受け入れる: 健全な文化では、すべてのフィードバックがコードを改善した、何かを教えてくれた、あるいは考えさせてくれたものとして歓迎されます.
 * 好奇心と実験を促進する: 安全な環境で、私たちは遊びを通じて学び、革新し、より楽しく取り組むことができます.
 * 謙虚に異論を述べる: 異論がある場合は、尊重をもって自分の意見を述べ、心を開いて考えを変えることができるようにしましょう. 何かが本当に重要かどうか自問してみてください. 代替案にチャンスを与えることを意欲的に行いましょう.



コミュニケーションの取り方が重要

 * トーンを考慮する: トーンは士気に影響を与えます. それによって、コードレビューが生産的で励みになり、やりがいのあるプロセスになるか、圧迫感のある、イライラする、傷つけるプロセスになるかが決まります. 親切で敬意を持ち、非判断的なトーンは、建設的なフィードバックを受け入れやすくなります. $1 「X が間違っています」と「Y を考慮したことがありますか?」のコメントは非常に異なる効果を持ちます.   The comments “X is wrong” and “have you considered Y?” have very different effects.
 * 意見を事実として述べない: 議論を終わらせる可能性があります. 代わりに…
 * 質問をして推奨事項を行う: 文脈を提供し、コードを改善する方法を説明し、その変更がどのような影響を与えるかを説明します. 説明文書へのリンクを提供すると、少なくとも一度調べたことがあることが示されます.
 * 「何を考えていますか?」と尋ね、返答に耳を傾けます.
 * 何かを事実として述べる場合は、正しいことを確認してください: そうではないと、コード作成者は時間を無駄にしてイライラします. 可能であれば、参照を提供してください. 何かについて確信が持てない場合は、代わりに質問してください.
 * 機能的な欠陥と好みの違いを明確に: コメントに明示的にラベル付けすることを検討してください.
 * 感謝と励ましを表現する: ポジティブな評価を追加することは必要ないと感じるかもしれませんが、感謝の機会に気付くようにしましょう. 何かを学んだり感心した場合は、言ってください. 感謝と励ましは、すべてのレビューに追加できます. 単純な「これをやってくれてありがとう」とか、「素晴らしい仕事だね」といった +2 のコメントでも、肯定的なフィードバックはさらなる貢献を促し、人々をより批判的なフィードバックに対して開かせるものです. Instead, be aware of opportunities to provide praise: if you learned something or were impressed, say so. Gratitude and encouragement can be a part of every review: even a simple “Thanks for doing this” or “Nice work!” with your +2 makes a difference, because positive feedback motivates further contributions and makes people more open to critical feedback.
 * 非難や皮肉を排除する: 著者ではなくコード自体をレビューしましょう. 誰でもミスをすることがあり、成長の余地があることを忘れずに、よい協力者はお互いの成長を手助けします. 批判的で皮肉なコメントは、協力的で生産的なコード レビューにはふさわしくありません. Remember that everyone makes mistakes and has room to grow, and good collaborators help each other grow. Judgmental or sarcastic comments have no place in collaborative, productive code review.
 * あなたが沈黙させているかもしれない人に気をつける: 否定的で絶え間ない批判の文化は、重要な声を沈黙させます.



大局を忘れずに

 * 文脈を見失わないように注意してください: 曖昧な問題や細かい指摘に集中する代わりに、コードがコードベース内で占める全体像に注目してください. 自分自身に「このフィードバックは有益か?」と尋ねることで、大きな目標を考慮してください. 一行ごとのレビューは重要ですが、プロジェクト全体の文脈の中で行う必要があります. あなたが貢献者を励ますことで、プロジェクト全体にとって長期的に貢献できることもあります.
 * さまざまなレビューの文脈に理解し、適応する: 経験豊富な貢献者による重要で複雑なパッチの場合、技術的な解決策を改善し強化することが主な目的になることがあります. 新しい貢献者によってアップロードされた小さなパッチの場合は、許容されたり教育されたりすることが重要です. 言葉遣いや批判レベルを手元の文脈に合わせて調整してください.
 * 一気に多くのコメントを残さないように注意する:$1 多くのコメントを一度に残すことは、著者にとって圧倒的なものになります. 特に複数のレビュアーによって行われた場合は、攻撃された気分になることもあります. 小さなパッチに多数のコメントを残す場合は、「これらのコメントは本当に必要か、価値があるのか」と自問してみてください. 多数のコメントを残さなければならない場合は、著者に個別に連絡し、助けを提供し、特別に親切にするように心がけましょう. Leaving a lot of comments at once can be overwhelming for the author, especially if done by multiple reviewers. It’s easy to feel ganged-up on. If you find yourself leaving a double-digit number of comments, especially on a smaller patch, ask yourself if these comments are really necessary or adding value. If you do have to leave a lot of comments, acknowledge this, ideally by reaching out to the author privately. Offer help and be extra kind.
 * 諦める: 妥協や敗北を優雅に受け入れる. $1 文書化された標準の一部ではない場合は、コード作者の好みを優先します. 完璧なコードというものはないことを覚えておいてください. 到底達成不可能な完璧を求めると、貢献者のやる気を奪い、進捗が遅くなります. 自分に問いかけて「このコードがそのままマージされた場合、最悪の場合は何か?」と考えます. 最善を尽くして、それから次に進みます. If it’s not part of documented standards, prioritise the code author’s preferences. Remember that there is no such thing as perfect code: a quest for unattainable perfection leads to frustrated contributors and slow progress. Ask yourself “what’s the worst case scenario if this code gets merged as-is?” Do your best, then move on.



思慮深い効率性

 * 明確さを目指す: ブロッカーとプリファレンスまたは明確化の要求との違いを明確にしましょう. 曖昧な表現や不完全な文は避け、自分の意見や必要なことを明確に述べます. どのように衝突が解決されるかを明確にします.
 * Provide complete reviews: Review the entire patch and raise every issue at the earliest opportunity. When a new patchset is uploaded, review only the new changes. Aim to merge the code in the fewest number of review/response cycles. If you don't feel able to provide a complete review initially (e.g. if the codebase or programming language is new to you, or for a very complex patch), consider discussing the patch with the patch submitter first.
 * ...and identify when you can't: If you don't feel able to provide a complete review, consider why: is it a question of experience, resourcing, or social dynamics? If the codebase or language is new to you, or for a very complex patch, consider discussing the patch with the patch author first.
 * Stay focused: A patch should have one idea and its consequences. If you see something in nearby code that you don't like, either as a reviewer or developer, make a note or file a task, don't add more changes to the commit. Big picture or architectural discussions should happen elsewhere.
 * Avoid nitpicking: Nitpicks are comments about minor, unimportant issues that distract from the ultimate goal of the review.
 * Two developers, given the same problem, will rarely write the same code. Respect creative differences. Don't repeat the work of the developer by asking them to write the exact code you would have written. The code just needs to be acceptable, it doesn't need to be perfect.
 * When writing a review, ensure that minor issues (like code style) are not the focus.
 * Frame your comments as helpful tips, not faults to be rectified. Mark nitpicks as such and do not allow them to block merging.
 * 素早く対応する: 批判的なフィードバックは、迅速に提供され、質問や更新されたコードへの迅速な回答があればよりよく受け入れられます.
 * 自動化する: 自動化することで、コード レビュー中の負担が軽減されます. できるだけ自動化し、繰り返しの議論がある場合は、自動化の可能性があるとして記録しておきます.

Refuse to normalise toxic behaviour

 * Use your privilege: Whatever form it may take, use the authority you have to lift up your collaborators and correct or reject toxic behaviour.
 * Return to values: When you see a problem, point it out and back it up with a reference to these values.
 * Learn from your mistakes: We all have room to grow—apologize sincerely and learn from your mistake, then move on.
 * Don’t adapt to a toxic culture: We shouldn’t waste time policing how many emoji or exclamation points we use. Instead, we should question toxic cultures.
 * Get help when you need it: Contact the project maintainers or submit a report to the Code of Conduct Committee.

Recommended reading

 * Compassionate coding: The secret of high performance teams
 * Unlearning toxic behaviours in a code review culture
 * The ten commandments of egoless programming
 * How to make good code reviews better
 * A guide to mindful communication in code reviews
 * Conventional comments
 * Non-violent code review
 * The seven principles of data feminism

Acknowledgements
Many thanks to everyone who provided ideas, feedback, and resources that went into creating these guidelines.