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

Scala Beginner Series (1) : Basics

ContribsGH-P The second way to implement a REST-API in Scala. Asynchronous version using futures.

Why not try Wagtail Cms?

Customize extent PDF report name in cucumber-jvm


Some Topic About Mongoose…

When you begin working at 85%, you may have to turn your rearview mirror toward

How the death of WebFaction changed my career as developer

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

Development on a weak system…

A Day in The Work Life of a Software Engineer in Australia

The Project Management ‘Instinct’

Tech Job switch after 2–5 YOE