As a developer who works in a team, I often have to give and receive feedback on code. This isn’t an easy thing to do. I myself experienced problems while doing this and there are some things we all should know to make the most of it.

What is a code review

Code review is systematic examination of computer source code. It is intended to find and fix mistakes overlooked in the initial development phase, improving both the overall quality of software and the developers’ skills.

Source: Wikipedia

By doing a “peer review”, as it is also called, you get some really nice benefits:

  • They can be used to establish conventions.
  • Share knowledge about the code base, best practices and what the team members have been working on (this could also speed up your standups).
  • Build trust in the team by understanding what people are strong or passionate about, their way of thinking and solving problems.

Ain't nobody got time for that

What is important as an author

  • When you create a PR, be sure to give some context. Use the comment box to explain WHAT you are doing, WHY and HOW. Also make sure to explain what problems you faced, if any.
  • Check your code once more before submitting, you might have committed unwanted changes or commented code.
  • Avoid creating long PRs, try to split them if that’s the case. Reviewing requires a lot of work and if the changes are many, people will either refuse to do it, or not be able to focus for the time required.
  • Be open minded and ready to receive feedback.

Git push and run!

What is important as a reviewer

  • What you are about to review is not just a changelist of code, you are looking at the implementation of a functionality, so take your time to checkout the branch, run the code and understand what the changes are and what they imply.
  • Try not to postpone it too much, the author is probably blocked by your code review.
  • Identify the scope and do not comment on things that weren’t part of the changes.
  • This is not just a place to comment on something wrong, it is also a place you can use to ask questions or give positive feedback.
  • Write clear and short notes. If they are too complicated, it might be a good idea to actually discuss them in person.
  • If you find the same issue repeated in the code, do not comment on each one of them. Write only one comment.
  • Be careful, what you are giving is written feedback, the author can’t hear your tone of voice or see your body language and this can cause misunderstandings (e.g. Avoid to use “you”, that might cause a feeling of judgement and prefer polite requests to statements).
  • Don’t be afraid of writing code examples to explain your ideas and always list the reasons behind your comments.
  • Don’t withhold approval round after round because you keep thinking of new ways for them to polish their code. The author will grow frustrated and feel you are blocking them.

Can't wait to see your code!


As I was reminded last week during an iOScon lightning talk by Abizer Nasir:

You are not your code, they are not their code.

This can be difficult to apply for many developers, me included, who tend to consider their code as their “baby”, or a work of art and interpret any criticism as personal.

So take it as a learning experience, the purpose of this is to improve code quality, not to judge you.

Please, feel free to add any comments to let me know what you think about code reviews and your experience.