What makes a good code review?

[cmc333333]

Lively discussion in chat; let's open 'er up.

[jcscottiii]

• "Comments, comments, comments"

You don't need comments everywhere but if there are any places that you have to think too long about what's going on, ask for a comment.

[jcscottiii]

I've seen during refactors or new projects moving rapidly fast that there can be dead code or unused code that may be left in.
The question to ask as you review is: "Can I remove this? / What would happen if I remove this?"

[jcscottiii]

"Does this variable name make sense?"

A real basic example:
Instead of having a variable named i where you might use it like i++
Name it idx if you using it to index something or
Name it count if you are counting something.

[jcscottiii]

"Does this function call account for all possible inputs/ outputs/ errors"

[jcscottiii]

"Is it possible to generalize some logic for extensibility"

[jmcarp]

An incomplete list:

High-level questions:

• Does the patch correctly implement the behavior described in the pull request or related issue?
• Is it clear how the implementation works (good variable names, inline documentation, descriptive tests, idiomatic code)? Will it be easy to read and maintain in six months?
• Are important changes covered by unit tests?
• Will the proposed changes work in a production environment (e.g. handle load, concurrency, production-sized data)?

Low-level questions:

• Does the patch meet team style conventions?
• Are unit tests readable and correct (e.g., don't over-rely on mocks, test corner cases)?

[dlapiduz]

If we are answering the question of "what makes a good code review" vs "what makes good code" then here are some thoughts:

• The review is thoughtful and respectful
• Nitpicking is limited to where it makes an impact
• The reviewer shows understanding of the project, the language and framework
• Points to specific lines of codes rather than the whole patch
• Doesn't interfere with the development flow

[cmc333333]

I see the best code reviews providing two types of benefits: a second set of eyes for finding errors and a learning opportunity.

Good reviews catch incorrect code -- subtleties missed by the original author. These might be getting business logic slightly wrong, missing a security or performance concern, misusing a library, off-by-one errors, etc. etc. Unit tests catch some of this, but I think that, from the perspective of a project, this is the primary use for code reviews.

More than that, though, good reviews offer suggestions on making working code better. These could take the form of pointing out difficult to follow reasoning, alerting of other libraries which might help, suggesting certain patterns and avoiding anti-patterns, using more concise style when it makes sense, and so forth. I think that these types of comments are the most helpful for our growth as developers -- they hone our craft through constructive criticism and commentary. They are, however, harder (if not impossible) to validate.

[pkarman]

big +1 to what @cmc333333 wrote.

[cmc333333]

@dlapiduz can you expand on

Doesn't interfere with the development flow

[dlapiduz]

@cmc333333 I think that there are some code reviews that come up every time you do a PR and prevent you/discourage you from sending more PRs... I don't think this is easy to watch at an individual layer but more at an aggregate one...

[jessieay]

I would like to expand upon the second part of @cmc333333's comment above ("More than that...").

At the recommendation of @baccigalupi, I re-watched this excellent talk on cultivating a code review culture: https://www.youtube.com/watch?v=PJjmw9TRB7s (shout out to @derekprior for doing a 👍 job with that talk)

In the talk, Derek cites research that shows that people think code review is about finding bugs, but really we don't find many bugs while doing code review. But that's OK! Because there are other, more important benefits to having a strong code review culture:

• Knowledge transfer
• Increased team awareness
• Finding alternative solutions

These are along the lines of what @cmc333333 said above.

Beyond having a shared vision for the goals of code review, having a good process in place only works if everyone in the organization is fully participating in code review.

Derek provides two interesting high-level tips for cultivating a code review culture.

The first is for the author: provide lots of context about the PR in the PR itself. Don't make reviewers hunt through GH issues or Pivotal Tracker. Don't make them look at a comment thread on a Trello card. Explain to the reviewers the why of the code so they can understand its purpose and suggest reasonable alternatives.

The second is for reviewers: ask, don't tell. What this really means is "take special care to be nice." Getting critical feedback is hard, and it's even harder when it comes via GItHub where it's impossible to read a person's tone. An antidote to coming off as cold is for reviewers to pose their input as questions to start a discussion rather than commands.

In the final part of Derek's talk, he covers three important topics that arise once you are actually doing code review: disagreements, what to review, and style.

Disagreements: these are inevitable. And they are good. Disagreements mean people are engaged, which means they are learning. Once code has reached a certain threshold of quality, any disagreement you have on a PR is going to be about tradeoffs. At this point, it's fine for people to agree to disagree. Following the tip for reviewers above should help keep the tone of the conversation positive even when two people disagree.

What to review: we each bring our own strengths to the table when doing a code review. Some people care a lot about naming, others about removing duplication or test coverage or reducing complexity. The goal shouldn't be for any org to come up with a list of things to look for when doing code review; the goal is for each individual person to bring their own strengths and interests to the table when doing a code review. And, over time, through expressing thoughts on the topics of interest that interest and related knowledge will be transferred to the rest of the team.

Style: this is where @ertzeid and the Code Style Guide working group come in. Style is important in the context of a code review. But people who review based on style are perceived negatively. So it's important to have automated tools to detect code style guides AND to write down preferred styles in a place outside of a PR so that the conversation can happen independently.

In summary:

What makes a good code review is a code review that achieves the three goals listed at the beginning of this commentessay:

• Knowledge transfer
• Increased team awareness
• Finding alternative solutions

My feeling is that people will only participate in a code review if they enjoy code review. I covered a lot in this comment because I felt it was all interesting food for thought on the topic of code review. Perhaps someone can give me some feedback on how to summarize all of these thoughts into something more digestible?

[booch]

The goals of a code review are to ensure:

• Correctness
• Maintainability
• Learning / improvement

Everything we do in a code review should derive from those.

I encourage teams to create a checklist of things to check in a code review, as it's easy to forget to look for things like security issues. Here's an example from one team I worked with.

However, you have to be careful to keep the focus on the high level goals, and not get stuck in the weeds. And everyone gets stuck in the weeds — especially on style issues, which is why having automatic style checking is definitely preferred.

If I were to write such a checklist today, I'd have the 3 goals at the top, in large bold letters. Then I'd try to find some resources with good suggestions on how to do good code reviews, including this page. Then I'd have the team decide which ideas will be most effective at achieving the 3 goals.

[booch]

This is a great conversation. I'd especially like to emphasize some of @jessieay's points.

A code review should be a conversation, not an argument. You shouldn't generally be telling someone that they need to make changes. Instead, ask questions and make suggestions. Try to get a better understanding of the trade-offs that were involved in their thinking. If you think there's a better way, ask if they considered it, and why they chose the way they did. The code review is not a one-way conversation — the code reviewer should be learning as much as teaching.

Thanks for sharing this development guide with the community.

[fureigh]

Another element: constructive tone on all sides. @ohrite's "Better Code Review" slides include some useful suggestions and go deeper than the surface: https://speakerdeck.com/ohrite/better-code-review

[tbaxter-18f]

@fureigh I think you're the last person here who was in on this conversation at the time. Do you think the thoughts were captured in the code review section? Is there additional work to do, or can we close this?

[jessieay]

I'd say we can close. This was opened to spark a discussion and the resulting guides content on code review can be added to if anyone sees anything missing.