Communication in Code Reviews

Everybody hates getting back a code review that is blocking a merge. Please don’t waste your colleagues’ time by making them guess which word you misspelled. Don’t make your colleagues read extra information they do not need to know. In cases where a discussion is necessary, this is usually best done in person or through a video call. It speeds up the process, allowing everyone to be on the same page. It will enable everyone to stop the other person and say, “Stop. I don’t understand what you mean. It should be clear after the review which comments (if any) need to be addressed before merging the code.

Check that the code can be built and deployed. Define the scope and intent of the code you are reviewing. Check that the code fulfills the purpose. Ensure all comments and discussions are related to maintainability, performance, or functionality.

Spell-check your comments and remove any unnecessary information. Discuss in person or over a call, and only write down the summary. Always check if the code can be built and deployed as is. Let the author know if they can merge the code.

Reviewing is only worthwhile if the build or another part of the deployment process succeeds. What should change for the user of the software? What should change for the person making the software? How much value does this change bring to the company? Check if everything works as expected, and if not, let the author know what is wrong without looking at the code. After you are finished reading and commenting on the code, review your comments.

Pause if you need to refresh for a bit. Try to read the comments from the perspective of the person receiving the feedback. Is it easy to understand what you are trying to say? Are the comments relevant?