DEV Community

Cover image for Effective COMMENTS on pull requests

Effective COMMENTS on pull requests

Tan on June 12, 2020

This post is not about how to write a good pull-request, for there is a lot of great material about that in this blog and also online. Instead, thi...
Collapse
 
peaonunes profile image
Rafael Nunes • Edited

Nice post! Those are very good points.
At Airtasker we found Conventional Comments to be very useful.
The idea is that you set the expectation around the comment before the comment. So it avoids a lot of assumptions on both parts of the reviewing process.
Everyone states clearly the objective of the comment, but also its urgency.
Your examples could look like:

question: I do not quite understand how updateClientInfo() works, could you give an explanation? Do you think it worth a brief in code documentation?

suggestion (non-blocking): We've been having some trouble with this APPLE...

suggestion (non-blocking): What do you think we call this function isBufferAvailable()...

suggestion: When this function executes with pi = 3.14, it causes a stack overflow...

We do not follow it strictly, but just by using some of its concepts improved a lot the quality of our reviews and also the empathy on both sides.

Collapse
 
tan profile image
Tan

Thanks for sharing Rafael! I will definitely use this for future reference.

Collapse
 
kehoecj profile image
Clayton Kehoe

Nice post! I like the approach of asking a lot of questions and have used that in my code reviews too. One counterpoint is that on teams with high levels of trust I would rather have the first example of PR comments. For example I would much rather someone say "m is not a good name for a variable, you should name it message" rather than coming over and having a side discussion on it. If I disagree, I can comment back and then other on the team can chime in.

Collapse
 
adamnator92 profile image
Adamnator

Good sharing, every developer should read

Collapse
 
mhsangar profile image
Mario Sánchez García

Recently started working with PRs and I think this will be super useful!! Thanks for your post, Tan 👌🏻👌🏻

Collapse
 
tan profile image
Tan

Thank you! Glad you liked it.
Hope you have a good time reviewing those.

Kind regards!

Collapse
 
riimako profile image
Riina Korpela

Those are very useful points! Sometimes it's just hard to keep the comments nice, and these are good tricks :)