Code Review Etiquette: A Gentle Guide to Avoiding Jerk Warnings

Code reviews are an essential part of the software development process, helping ensure code quality and sharing knowledge within teams. However, poorly executed code reviews can easily make the reviewer come across as a jerk, which can be detrimental to team morale and collaboration. This article explores effective communication strategies to make code reviews more productive and less likely to offend.

Use 'I Statements' Over 'You Statements'

Avoid using accusatory language like 'You wrote' or 'You did', which can quickly put the reviewer on the defensive. Instead, use 'I' statements to express your thoughts and suggestions. For instance:

I think changing the order of these three statements would make their goal clearer.

is far more constructive than:

You wrote these so they really obscure the process right here.

Utilize Questions Over Direct Statements

Avoid making direct statements like 'It is better to do it the X way. ' Instead, frame your suggestions as questions. This approach encourages the author to reflect on their choices and can lead to a more productive discussion. For example:

Would it not be better to do it the X way rather than the way you have chosen?

is more constructive than:

It is better to do it the X way rather than the way you have chosen.

An Experiment in Collaborative Code Reviews

Traditional code reviews often take a top-down approach, where the reviewer critiques the author's work. However, Google's SEOer recently experimented with a new format and found it highly effective in engaging teams and sharing knowledge. In this new process, the author leads the code review, discussing their compromises and the SLA (Service Level Agreement) met.

A Promising New Format

By having the author lead the review, this process shifts the focus from the reviewer to the author. The author can present their code, explain their decisions, and discuss future refactorings and tech debt. Reviewers can provide feedback and ask questions, fostering a collaborative environment. The author often takes the harshest stance, explaining their rationale, while the forum supports and defends the choices.

Implementation and Outcomes

This new format has been implemented across a few teams, and initial feedback is promising. The author is usually the harshest critic, which sets the tone for constructive criticism. The forum hears and often defends the choices, leading to increased engagement and a deeper understanding of the codebase. Here are some key outcomes:

Increased engagement and awareness of what is in the code repository. Periodic validation of deliverables from a business point of view by product support and business stakeholders. In some cases, alternate ways of achieving the same goals are presented and implemented.

One indication that the process is working is the willingness of the forum to consider and implement alternative approaches. This not only validates the process but also contributes to continuous improvement in the codebase.

Conclusion

Effective code review etiquette is crucial for maintaining positive team dynamics and ensuring the quality of the code. By using 'I statements' and 'questions' instead of direct statements, and engaging the author in a collaborative manner, the process can become more productive and less likely to offend. Experimenting with new approaches, as described here, can lead to significant improvements in team collaboration and code quality.