DEV Community

Cover image for Mastering Code Review: A Guide for Reviewers and PR Creators
Tássio
Tássio

Posted on • Edited on

Mastering Code Review: A Guide for Reviewers and PR Creators

Code reviews are essential for code quality, team collaboration, and to make sure that best practices are followed in the development process. Guess no news so far, however, effective code reviews requires more than just looking for bugs or syntax errors. Let's take a look in the best practices for conducting code reviews from the perspective of the reviewer and the pull request creator.

For Reviewers 🔎

  1. Be constructive: Provide feedback in a constructive and respectful way. Focus on improving the code rather than criticizing the developer. Being polite is always good xP

  2. Understand the context: Take the time to understand the purpose and requirements. This will help you provide more relevant feedback.

  3. Review the code, not the person: Remember that code reviews are about improving the code, not attacking the developer.

  4. Be specific: Provide specific comments and suggestions. Avoid vague or general feedback that may confuse the developer (one of the most important, in my opinion).

  5. Prioritize issues: Identify critical issues that need immediate attention and non-critical one that can be addressed in the future. This will help the developer focus on the most important.

  6. Offer alternatives: Instead of just pointing out problems, suggest alternative solutions or improvements.

  7. Consider the bigger picture: Think about the impact of the changes on the overall system. Consider scalability, maintainability, and performance aspects during the review.

  8. Remember of deadlines: Review code promptly to avoid delaying the development process. If you need more time, communicate it to the pull request creator.

  9. Avoid "Pull Request Friendship" : Do not approve a pull request just because the creator is a friend or because you have faith in their deliveries. Every pull request should be reviewed objectively, based on the quality of the code and its adherence to project standards and best practices. This ensures fairness and maintains the integrity of the codebase.


Enjoying it? If so, don't forget to give a ❤️_ and follow me to keep updated. Then, I'll continue creating more content like this_


For Pull Request Creators 💻

  1. Prepare your code: Before submitting a pull request, make sure your code is clean, well-structured, and follows the project's coding conventions. This will make the review process smoother.

  2. Utilize repository features: Assign the pull request to yourself, use a clear and descriptive title and apply labels. Maintaining an organized repository is straightforward, easier fot future filtering and searching, and fosters a healthy codebase to work with.

  3. Provide context: Include a clear description of the changes made and the problem being solved. This will help reviewers understand the purpose of the code and also make easier to future investigations.

  4. Be open to feedback: Be receptive to feedback and willing to make changes. Remember that code reviews are (should be) an opportunity to improve the quality of your code.

  5. Engage in discussions: Respond to comments and questions from reviewers.

  6. Learn from the review: Use the feedback received during the code review to improve your coding skills. Take the opportunity to learn from more experienced developers.

  7. Address all comments: Address all comments and suggestions made by the reviewers. If you disagree with a comment, provide a clear explanation and discuss it with the reviewer.

  8. Test your changes: Before marking the pull request as ready for merge, ensure that your changes have been thoroughly tested and do not introduce any regressions.

  9. Keep it concise and context-specific: Concentrate on delivering within the context and avoid modifying files outside the scope. Smaller pull requests are easier to review and reduce the overall time for pull request approval.

  10. Be grateful: Show appreciation to the reviewers for their time and effort in providing feedback. A simple thank you is enough and creates a positive code review culture. ❤️

Buy me a coffee ☕. Hope I have helped you somehow. 🤗

See my other articles and my open source project

Top comments (28)

Collapse
 
michaliskout profile image
Michael

Great post that will be very helpful for teams to improve their communication, particularly in the area of PR reviews.

I would like to add two additional points based on my experience so far.
For PR creators.
Make your PR as small as possible: Small PRs help reviewers to quickly understand the intent of the changes, eliminate the danger of missing a potential issue in a huge PR, and avoid receiving a huge number of PR comments that may delay PR merge.

For PR reviewers.
Take it offline: If a conversation in PR comments has more than two replies on the same topic, try to understand and resolve the conflict in a quick adhoc one-on-one meeting if possible. This shows that you truly care and want to resolve the conflict as soon as possible in order to avoid any delays in the PR merge.

Collapse
 
canro91 profile image
Cesar Aguirre

And to expand on your last point: bring the conclusions made offline back to the PR itself for other reviews

Collapse
 
tassiofront profile image
Tássio

Amazing points, Michael! I totally agree with your two considerations

Collapse
 
ccoveille profile image
Christophe Colombier • Edited

I approve your article. I'm a senior engineer, and a good reviewer.

I like how your article is related to mine and what I explained about cognitive biases.

For example, the "avoid pull request friendship" is such a good point. It relies in confirmation and error attribution biases. It's almost the same for "review the code, not the person"

If you want good review and to improve yourself. You must face people who disagree with you. We learn from our failures

Collapse
 
tassiofront profile image
Tássio

Thanks a lot for your comment, Christophe! I'm also a code review lover, and I think that is a worthwhile moment. We can learn, practice, and teach.

Thanks for sharing your article. It's an important subject and, to be honest, I need to reflect on it.

Collapse
 
italolourenco profile image
Italo Lourenço

Really a good article! It brought me several points of reflection about my way of working. Thank you very much for that.

If I could contribute here, I would add a point about creating a pull request. I believe it's also very valid to have a description of how to test that feature. It's not always easy to validate something in production or staging environments, but having a path to follow already helps a lot and serves as a way to explain more about the context of the feature, making the review easier later on

Collapse
 
tassiofront profile image
Tássio • Edited

Amazing remember,@italolourenco! Thanks a lot for your suggestion and feedback!
I have created the 3.Provide context about this 🚀

Collapse
 
mnathani profile image
Murtaza Nathani • Edited

Amazing points, I try to follow most of them..

As an engineer, I consider PR reviews a vital step in development process.

For my experiences I would like to add is:

Create a pull_request_template.md file on .github folder . Add all the points as a checklist you think are important in your company for PR creator to mark while creating the PR.

There are tons of template online, pick one and change it to your needs and add it. Helps when you scale and also reminds to always do those tasks.

Example: github.com/cezaraugusto/github-tem...

Happy coding!

Collapse
 
tassiofront profile image
Tássio

Thanks for amazing remember, Murtaza 🚀

Collapse
 
dsassoli profile image
Daniele • Edited

I agree with pretty much everything here, however, I'd like to push it one step further. What about not following the pull-request model at all? I find stacked-commits in the style of tools like Gerrit offer a much better code review experience, both for the reviewer and the developer. Helping greatly in keeping reviews small and isolated. Being able to comment on the commit message itself is also a great advantage.

Collapse
 
tassiofront profile image
Tássio

I have never heard about Gerrit, thanks a lot for sharing, Daniele. I'll take a look at it, looks great.

Collapse
 
dsassoli profile image
Daniele

Sure. Essentially it helps greatly with keeping PRs(Which are called Changes in the Gerrit world) small, by enabling stacking of commits, which can then be reviewed and updated individually, while still making it easy to test the whole chain of commits as one.

This way, developers don't need to compromise between keeping PRs small or creating separate PRs, which are then a nightmare to maintain and merge separately.

Also, having the commit message as the "PR Description" helps greatly in keeping a clean and expressive git log, helping future debugging.

Collapse
 
kirkkm profile image
Kirk

This is amazing and easily overlooked part of the job as a software engineer/developer. The difference between a good and a great engineer/developer is this right here, PR reviewing and creating skills.

Collapse
 
tassiofront profile image
Tássio

Thanks a lot for your comment, Kirk!

Collapse
 
pwd9000 profile image
Marcel.L

Nice article! I wonder if I can make an AI copilot to do my PR reviews for me in this season of AI… 🤔

Collapse
 
dsassoli profile image
Daniele

Gerrit already supports integration with ChatGPT, I'm sure GitHub and GitLab have something similar.

Collapse
 
best_codes profile image
Best Codes

Awesome article!
Very interesting. I learned a lot, thanks for writing!

Collapse
 
tassiofront profile image
Tássio

thanks for the feedback, @best_codes 🚀

Collapse
 
fabrikapp profile image
Fabrikapp

Pretty good rules ! Always good to keep in mind.

Collapse
 
ccoveille profile image
Christophe Colombier

Hey @tassiofront

I thought about you and your article by writing this, 🤣😂

dev.to/ccoveille/comment/2eob1

Collapse
 
tassiofront profile image
Tássio

hahahaha great comment, @ccoveille 😂😂😂😂 I remember the biggest PR I have reviewed: more than 7000 lines changes (1 feature). I have had nightmares since then... I don't wish it on anybody else. 😜

Some comments may only be visible to logged-in visitors. Sign in to view all comments.