Reviewing the Code Review, Part I

Some of our customers are telling us that they are using CodeStream to shorten code reviews by as much as 50%. It’s a lightweight approach, and we are trying to learn from their experience and feedback, and improve on the processes and features we offer to make those code reviews even better. CodeStream introduces the concept of a continuous code review, a light-weight, in-editor process that enables the review of any part of your codebase, at any time. Making code review continuous means you can get feedback earlier in the process as you are stubbing out functions and classes, during heavy development while you are building a new feature, immediately prior to merge as you seek feedback from your team, and importantly even for code that was merged some time ago, as you come across technical debt in your codebase.

What’s wrong with code reviews?

According to Traci Lum in her article How to Give and Get Better Code Reviews, code reviews are among the most dreaded activities by developers. Developers, who typically spend much time creating, imagining, and inventing (often on their own and without interference), face an uncreative procedural judgment. She writes: “...it’s a time when you, the developer, the craftsman, the artist, present your work before a council of critics and beg them to bless your masterpiece with a thumbs-up emoji and a “LGTM.””.

Code reviews are, of course, necessary to maintain code quality. Why such dread? What can be done to reduce it significantly? What are the benefits of a different approach? Much of what’s wrong with code reviews boils down to three elements:

1. the time elapsed between code being written and code being reviewed,
2. the context switching imposed by the very process, away from the code and into the browser or to a different context outside your IDE, and finally
3. the fact that a typical review looks at any given code only once – it’s being readied for deployment – and does not contemplate a continuous improvement process.

In this context, let’s discuss some of the suggestions provided by Traci on how to improve the code review process, and suggest improvements to the improvements.

Developers generally live in their IDE. That is the place where code is written, changed, compared, etc. The reason why code reviews are not performed in your IDE is an accident of timing. Had IDEs been more extensible earlier, we would have seen all the benefits of performing code reviews in context and the disjointed nature of the process might have been avoided.

Your IDE is the best place to discuss code

Traci Lum’s suggestions are helpful and reasonable and they are centered on improving the PR process. Let’s summarize her recommendations while addressing potential improvements that could be made if the code review was started earlier and originated in your IDE instead of a PR.

If you want to get better code reviews, her suggestions include:

• Linking to the GitHub issue or JIRA ticket from the body of a PR
  • What if there was no PR and you could instead generate or attach a Jira ticket or GitHub issue to the code itself from your IDE, assign someone to fix or review, and have that link be permanent and visible to any teammate perusing the code?
• Writing a quick summary or list of the changes, trade-offs, and remaining todos
  • What if the summary of the changes was just an automatic report being generated within your IDE including all the questions and concerns?
• Tagging pull requests with labels, and Review your own code before you officially put it up for review
  • What if you could tag and comment on any code block and make that easily accessible in editor for all the devs in your team?
• Annotate places where you’re especially unsure or want feedback
  • What if you could just do that at any time as you write code, even before a PR, so that the feedback can help you avoid a dead end, thus reducing errors and technical debt?
• Tag the right people
  • What if once you select any code block in your IDE there was an instantaneous git blame lookup to let you know who wrote or edited that code and that person was @mentioned in your composition box automatically?
• Take a breath and internalize the reviews.
  • Always good advice. What if the whole conversation was saved and accessible to both parties (and ultimately to any dev on the team) as useful documentation that explains how decisions were made?

If you want to give better code reviews, her suggestions are:

• Ask questions instead of making statements, that is, fewer WTFs
  • What if you could share a code example to illustrate a solution and it was linked to the review automatically?
• Articulate the problems (if any) and suggest alternatives
• Try to understand the context and the proposed solution
• Highlight wins (by which she means, be positive when giving feedback)

If the PR is to remain the primary place where a code review takes place, all of the steps suggested by Traci in order to improve the process would be fine. However, if we are prepared to consider beginning the review process earlier, prior to a PR, unencumbered by the PR, the code review becomes continuous, that is, at any time, on any line of code, about any issue.

In Part 2, we will explore other suggestions for improving the code review, and offer ideas on how to make things even easier, more productive, and more pleasant.