A guide for Code Reviews

Code reviews shouldn’t be about ego. Still, every time you send one, you’re putting yourself out there. You want your work reviewed but at the same time it makes you vulnerable. The point isn’t to tear each other down, it’s about shipping solid code and not screwing the team over.

Bad CRs waste time: vague descriptions, missing tests, or five unrelated changes crammed together. Bad reviews waste time too: nitpicking style, forcing personal preferences, or dragging things into endless comment wars.

These guidelines exist so we can trust the code we merge, move faster, and keep the focus where it belongs, building good software together.

CR Submission Guidelines

1. Keep CRs Focused
   Submit one CR per feature whenever possible. If a feature is large, break it into multiple CRs, each focused on a specific aspect.
   Example: A “user history” feature may require both database access and a user interface. Submit database changes first, followed by the UI.
2. Write Clear, Documented Code
   Ensure your code is self-explanatory and includes appropriate comments and documentation.
3. Test Before Submitting
   Always include unit tests with your CR. Adding tests later often leads to weaker coverage and missed scenarios. If possible, attach test coverage reports using standard tools.
4. Provide Context
   Add a clear description to your CR. For larger changes, consider scheduling a whiteboard or design review session so the team understands and agrees on the proposed solution.
5. Use the Issue Tracker
   Reference related issues in your CR title and body. This makes the review easier to trace back to requirements or bug reports.
6. Separate Unrelated Changes
   Don’t combine unrelated changes in the same CR. If something urgent comes up, create a new branch and submit it separately.
7. Follow Conventions
   Adhere to your team’s coding standards and formatting. Consistency across the codebase is more important than personal style.

Code Reviewing Guidelines

1. Understand the Goal
   Read the CR description, linked issue, or related design documents before diving into the code.
2. Give Constructive Feedback
   Provide context with your comments so the author understands your concern.
3. Ask, Don’t Accuse
   Phrase feedback as questions rather than accusations.
   Example: “What was the reason for not using the standard library method?” instead of “You didn’t use the standard library method.”
4. Acknowledge Good Work
   Call out code snippets, design choices, or approaches you find effective. Positive feedback encourages good practices.
5. Use Design Discussions Wisely
   If a CR requires extensive back-and-forth, schedule a design session rather than leaving dozens of comments.
6. Respect Different Approaches
   There are often multiple valid solutions. Don’t enforce personal preferences if the submitted solution works well.

For both reviewer and sender

• Don’t take feedback personally.
• Someone will always know more. Be open to learning.
• Challenge ideas, but accept when others have stronger reasoning.
• Treat each other with respect. Always.

At the end of the day, code reviews are about respect for the craft, for the codebase, and for each other. Follow these guidelines, keep CRs focused, give context, write tests, review fairly, and don’t let ego get in the way. If we stick to this, we’ll waste less time, argue less, and ship better software together.