Guidelines for a healthy code review culture/ja

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

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



コードレビューの目標

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

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



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

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


 * フィードバックは歓迎される: 健全なコードレビュー文化では、フィードバックを受け取ることは、本番環境に進む前に問題点が発見され、知識が共有され、人々が協力してコードを改善することを意味します. このような文化で作業することには、やりがいがあります.
 * 恐れなく: 心理的安全性は、健全なコードレビュー文化の基盤です. 人々はフィードバックを提供したり受け取ったりするために、快適な気持ちでいる必要があります. パッチを提出したり、批判を行ったりすることは、圧迫感を感じることがあり、このプロセスには信頼が必要です. 安全な環境にいる人たちは、新しいアイデアを提案したり、実験したり、成長したりできます. 安全を感じない人たちは、やがて貢献を止めて去っていってしまいます.

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



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


エゴよりも尊重と共感

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



競争よりも協力

 * 協力に重点を置くこと: 協力に注力すると、エゴが邪魔をすることはありません. 協力は、多くの人々が貢献することを可能にし、より良い製品を生み出します.
 * 協力の課題を認識する: 私たちの中には、トーンを管理するのが難しい人、好きではない解決策に譲ることに苦労する人、批判的であることを避ける人もいます. みんな違うけど、成長できるんだということを覚えておいてください.
 * Embrace feedback as a gift: In a healthy culture, every piece of feedback will be welcomed as something that improved the code, taught us something, or made us think.
 * Encourage curiosity and experimentation: In a safe environment, we can learn, innovate, and have more fun through play.
 * Disagree with humility: When you disagree, state your opinion respectfully, and be open to having your mind changed. Ask yourself if something really, truly matters. Be willing to give alternate solutions a chance.

How you communicate matters

 * Consider your tone: Tone impacts morale. It determines whether code review is a productive, encouraging, and fulfilling process, or an intimidating, frustrating, and hurtful one. A kind, respectful, and non-judgmental tone will make people more open to constructive feedback.   The comments “X is wrong” and “have you considered Y?” have very different effects.
 * Don’t state opinion as fact: You might shut down discussion. Instead…
 * Ask questions and make recommendations: Provide context, explain how the code could be better, and outline the impact of changing it. Provide links to documentation—doing so demonstrates that you had to look it up at least once.
 * Ask "what do you think?" and listen to the response.
 * If you do state something as fact, make sure you’re right: Otherwise, the code author will waste time and be frustrated. Provide references if possible. If you’re not sure about something, ask questions instead.
 * Be clear about what’s a functional defect and what’s a preference: You might consider explicitly labeling your comments as such.
 * Express gratitude and encouragement: “Positivity” is a loaded term, and advice like “add praise to every review” can seem fake or unnecessary. 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.
 * Leave out judgment and sarcasm: Review the code itself, not the author. 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.
 * Be aware of people you may be silencing: A culture of negativity and unrelenting criticism silences important voices.

Remember the bigger picture

 * Don’t lose sight of context: Instead of focusing on obscure issues or nitpicks, focus on the overall place of the code within the codebase. Consider the larger goal by asking yourself “is this feedback valuable?” Line-by-line review is important but should be done within the context of the project as a whole. You may help the project more in the long run by encouraging a contributor rather than frustrating them.
 * Understand and adapt to different review contexts: For a significant, complex patch authored by a seasoned contributor, refining and strengthening the technical solution might be the primary goal. For a small patch uploaded by a new contributor, inclusion and education are more important. Adapt your language and level of criticism to the context at hand.
 * Avoid leaving an avalanche of comments: 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.
 * Let go: Gracefully accept compromise or defeat. If it’s not part of documented standards, prioritize 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.

Thoughtful efficiency

 * Automate: Everything you automate is no longer a burden during code review. Automate as much as you can, and note repeated discussions as potential opportunities for automation.
 * Aim for clarity: Be clear about what you consider a blocker as opposed to a matter of preference or a request for clarification. Avoid euphemisms and incomplete sentences: clearly state what you mean and what you think needs to happen. Make it clear how conflicts will be resolved.
 * Keep patches small: Large patches are difficult to review and may languish in code review for too long. Authors should submit small patches, but reviewers should also avoid asking for unrelated work in a patch and should err on the side of resolving issues later when possible. Big picture or architectural discussions should happen elsewhere.
 * …but provide helpful review: Not enough feedback is a problem, too. Cursory reviews don’t spark discussion or foster education. If sufficient reviews aren’t happening, consider why: is it a question of resourcing, social dynamics, or something else?
 * Avoid nitpicking: Most nitpicks are unnecessary to the ultimate goal. Follow this process:
 * For any comment, ask yourself if it’s a nitpick.
 * If it is, consider deleting it.
 * If you must nitpick, label the comment as such and make it non-blocking.
 * Consider whether that nitpick could have been identified via tooling.
 * Respond quickly: Critical feedback goes over better if it’s provided promptly and followed up with quick responses to questions or updated code.

Refuse to normalize toxic behavior

 * Use your privilege: Whatever form it may take, use the authority you have to lift up your collaborators and correct or reject toxic behavior.
 * 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 behaviors 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.