Code Review Guidelines

Code reviews are a necessary and important step of the software development lifecycle and having a solid process can improve both the quality and speed of delivery. It also has the added benefit of sharing what we work on with our teammates.

Here are some general guidelines to help make your team’s code reviews better. These guidelines can be applied to a wide range of source code — from application development to infrastructure. Let this be a starting place to build good habits on code reviews.

General Guidelines

  • Peer reviews should be thoughtful and compassionate.
  • Comments should be constructive, not critical.
  • Include code samples and links if possible.
  • Merged code reflects the whole team not just the individual.
  • High level decision making should be done in project planning, not in code review.
  • Find good things to say!

Where to start

Questions to consider when reviewing code and tickets:

  1. Does the solution presented solve the problem in the best way possible?
  2. Does the solution follow coding standards and best practices established by the team?
  3. Is the code readable and maintainable?
  4. If there is opportunity for documentation, was it included (ADR’s, Runbook, README, etc.)?
  5. Is there adequate test coverage?

Types of comments

Sometimes we want to make a light suggestion, or ask a clarifying question, but not block the pull request from being merged. We can tag our comments as such with — [comment], [question], [blocker], and [recommended]. You can use Github saved replies to make it easier.

Here are some examples of each:

  • [blocker]: we shouldn’t merge the code until this is resolved. potential to cause an issue in production, misalignment with team’s established coding standards, code doesn’t function as intended
  • [question]: A question to provide clarity or explanation. “Why is the default set to 2?”
  • [recommended]: Offer a clear and precise recommendation. “We can improve performance by changing this line of code to be… [code snippet]”. “As a suggestion, the variable name descriptive_variable_name could read better here."
  • [comment]: “Nice work!”, variable/class/object name isn’t clear, formatting, code isn’t readable

Receiving reviews

Responding to code reviews takes just as much careful consideration as reviewing. Take the time to consider all comments and feedback, not just blockers.

Useful reads that helped build this post

Five tips for more helpful code reviews

What makes a good code review?

Creating Simple and Effective Guidelines for Code Reviews




a journal of engineering

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

The GidTech Where-U-At 2000™

Mac Mini Raid Array

Mac Mini Raid Array

Ruby on Rails in the US Market

MoSCoW Method: How to Make the Best of Prioritization

Introduction to C

Fetch/Execute Cycle

TryHackMe |Year of Rabbit 🐰

Wildcard domain issuer with azure DNS/Nginx ingress/Cert manager/Kubernetes

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store


a journal of engineering

More from Medium

The Steps in making a Software

Make Your Software Development Flow More Efficient

Is Visual Basic Still Relevant Today?

What is Pair Programming in software engineering?