Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
An incomplete list:
If we are answering the question of "what makes a good code review" vs "what makes good code" then here are some thoughts:
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.
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
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:
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.
What makes a good code review is a code review that achieves the three goals listed at the beginning of this commentessay:
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?
The goals of a code review are to ensure:
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.
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.