Code Review Guidelines

Sometimes developers frown upon code review. But most complaints about the code review process are actually resolved by making the process faster.

The main goals of code reviews are:

• code health of a code base should improve,
• both the author and reviewer learn.

There is no such thing as “perfect” code—there is only better code.

A reviewer should seek continuous improvement, not perfection.

GitHub has pull requests (PR), GitLab has merge requests (MR). They are equivalent.

Don’t let the code change (PR/MR) sit around because the author and the reviewer can’t come to an agreement.

Tests can automatically detect bugs but a human must ensure that those tests are valid.

In doing a code review, you should make sure that:

• the code is well-designed,
• the functionality is good for the users of the code,
• any UI changes are sensible and look good,
• compatibility breaking changes are treated,
• code adhere to good programming principles (YAGNI, KISS, DRY, naming, commenting, …)
• tests are well-designed,
• code is appropriately documented,
• the code conforms to style guides/guidelines.

Look at every line of code that you have been assigned to review. Look at the context, make sure the code health is improved.

Compliment developers on good things they do.

It should be clear what is nitpicking, what requires changes, what requires an explanation etc. It is useful to mark code review comments with labels as hint, suggestion, critical, question, remark, nit etc.

Resources

• Google Code Review Guidelines
• Semantic Reviews

My former colleague used to add memes to code reviews–a custom from when he was working at Facebook. I like it and in the gallery I will be collecting such memes which I use from time to time.