August 22, 2016 · meta

Trial by Code Review

Today wasn't the day, but I remember it like it was. My first big project that I submitted at a big company working with engineers that I respected and looked up to. I pushed my code to our code review tool and anxiously awaited their feedback. Some of it was the most unconstructive feedback that I've ever seen in a code review and since then I've thought of some standards that might (or might not) be worth adhering to in code reviews. Perhaps a better title for this post is actually A brief guide to writing code reviews.

Code Review Features

For the sake of simplicity (and completeness of the tool), I'm going to assume that your code review tool has the following features:

Tips for Commenting on Lines of Code

Commenting on one or more lines of code is one of the best features that a tool like this offers. It allows you to provide suggestions and ask questions in the context of a specific function, scope, or operation. That being said, there are some things you should do when commenting on one or more lines of code.

Tips for Commenting on the Request

Sometimes, you have comments that aren't necessary relevant to a single line. Perhaps a question about how this fits into the bigger picture or maybe you want to suggest a different design pattern. The "top of the review" - that is, not tied to a specific line - is the place to do this.

Flagging a Comment as an Issue

Arguably the most useful feature of any code review tool is the ability to flag something as an issue. Great code review tools will also group the issues and/or allow you to see each issue raised side by side with your code. If you're flagging a comment as an issue, here's a few things to keep in mind:

Granting Your Blessing

If your code review tool provides this feature, it's important to leverage. Review Board, a tool that I frequently use, has a checkbox called "Ship-It!" which is used to grant your blessing on this change. At LinkedIn, you can't ship code changes without a "Ship-It!" from the code owners. When you're granting your blessing, it's a good time to recap the history of this review request. Consider doing the following:

  • LinkedIn
  • Tumblr
  • Reddit
  • Google+
  • Pinterest
  • Pocket
Comments powered by Disqus