Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

What makes a good code review? #5

Closed
cmc333333 opened this issue Oct 21, 2015 · 17 comments
Closed

What makes a good code review? #5

cmc333333 opened this issue Oct 21, 2015 · 17 comments

Comments

@cmc333333
Copy link
Contributor

@cmc333333 cmc333333 commented Oct 21, 2015

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

@jcscottiii

This comment has been minimized.

Copy link

@jcscottiii jcscottiii commented Oct 21, 2015

  • "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

This comment has been minimized.

Copy link

@jcscottiii jcscottiii commented Oct 21, 2015

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

This comment has been minimized.

Copy link

@jcscottiii jcscottiii commented Oct 21, 2015

"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

This comment has been minimized.

Copy link

@jcscottiii jcscottiii commented Oct 21, 2015

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

@jcscottiii

This comment has been minimized.

Copy link

@jcscottiii jcscottiii commented Oct 21, 2015

"Is it possible to generalize some logic for extensibility"

@jmcarp

This comment has been minimized.

Copy link

@jmcarp jmcarp commented Oct 21, 2015

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

This comment has been minimized.

Copy link

@dlapiduz dlapiduz commented Oct 21, 2015

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

This comment has been minimized.

Copy link
Contributor Author

@cmc333333 cmc333333 commented Oct 21, 2015

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

This comment has been minimized.

Copy link
Contributor

@pkarman pkarman commented Oct 22, 2015

big +1 to what @cmc333333 wrote.

@cmc333333

This comment has been minimized.

Copy link
Contributor Author

@cmc333333 cmc333333 commented Oct 22, 2015

@dlapiduz can you expand on

Doesn't interfere with the development flow

@dlapiduz

This comment has been minimized.

Copy link

@dlapiduz dlapiduz commented Oct 22, 2015

@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

This comment has been minimized.

Copy link
Contributor

@jessieay jessieay commented Oct 28, 2015

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

This comment has been minimized.

Copy link

@booch booch commented Oct 28, 2015

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 comment has been minimized.

Copy link

@booch booch commented Oct 28, 2015

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

This comment has been minimized.

Copy link
Contributor

@fureigh fureigh commented Nov 4, 2015

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

This comment has been minimized.

Copy link
Member

@tbaxter-18f tbaxter-18f commented Jun 17, 2019

@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

This comment has been minimized.

Copy link
Contributor

@jessieay jessieay commented Jun 17, 2019

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
9 participants
You can’t perform that action at this time.