Effective COMMENTS on pull requests
Tags: productivity, github, discuss
Published: 2020-06-12 23:25:50

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, this post is about writing an effective **comment** on pull requests. 

I'm not the first to come up with this topic. During my last internship, I attended an amazing discussion titled *"Effective Code Reviews"*. The focus was on the reviewers themselves, rather than on the author. 

Since then, I wanted to share more of what was discussed. Thus, I hope that this post helps you write better comments, but also allows us to further discuss this topic. 

## Introduction
So you might say: 

*"When I review a pull-request, I know how to approach someone with constructive feedback. I would never write:*

![A mean comment. Please don't ever do this.](https://dev-to-uploads.s3.amazonaws.com/i/fhbp04woy7lc42mcea26.png)*So how could I possibly be as effective as that?*"

First of all, yes. Please **never** write something like that. Indeed, explicit toxic behaviour is easy to identify and avoid. However, sometimes we unintentionally may harm each other with a seemingly innocent suggestion.

We as humans cannot run away from our nature. We are inherently defensive. That's how our brains work. We have our biases, our preferences, our beliefs, and **that's fine**! 

## A (not) very uncommon scenario
With that said, the point of a pull-request is not to write impeccable code. It's for us (author and reviewers) to learn how to improve the current state of our codebase. 
So how, in doing so, can we accidentally harm our effectiveness (and ourselves)?

Let me tell you a story:
After two weeks, you finished the most expected feature of your *P.I.E.* system for this iteration. You've spent hours and hours reading your code, looking for *typos* and trying to test everything as much as possible. It is finally time to deploy it, and you submit a PR to the production branch. 

You and I work on the same team, so you add me as a reviewer to your PR. Then, you go do something else, while I review your changes before I can approve it.
You take a sip of your coffee, and can't contain a smile. You've done it. After all this time, you're allowed to rejoice.

However, thirty minutes later, you see that I've left some comments on your PR. You open the page, and see this:
![Some comments that aren't exactly ill-intended.](https://dev-to-uploads.s3.amazonaws.com/i/pyva9d3qnmv8w404nsf0.png)

...Let's say this goes on for more five comments or so.
How would that make you feel? 

You're not necessarily *offended*... But you do not feel good either... right?

Instead, look at the parallel universe in which I left a different set of comments: 
![Somewhat more kind comments. Would you agree?](https://dev-to-uploads.s3.amazonaws.com/i/xlgcahhf7clop2voexgz.png) How would you feel reading those instead?

## Effectively reviewing a PR
### Leave more questions than suggestions
Ask a lot. You should first understand what the code is doing, before even trying to suggest an improvement. This helps to achieve two things: 
- you learn more about the code
- you could help the author spot a small bug that they didn't notice.

![Ask more questions than leave suggestions.](https://dev-to-uploads.s3.amazonaws.com/i/y04hfmhwrawj2nzwg6pa.png)

PS: If you've discussed something in-private, remember to add an update so other people from the team who might have the same question also know what was discussed.
![Leave updates if something was discussed in-private.](https://dev-to-uploads.s3.amazonaws.com/i/tkq1t43lfrx7bycu2cnq.png)

### You can also leave compliments
I would highly encourage you to do so if you can. Pull requests aren't only for pointing out things to improve. You can also point out positive things, like:
![A nice positive thing.](https://dev-to-uploads.s3.amazonaws.com/i/woa7hlc8aa613897n4w0.png)

![Another positive thing.](https://dev-to-uploads.s3.amazonaws.com/i/hil5yh641sfibsp052j3.png)

### If it's too big of a change
We want to write the best code we can, but sometimes we have to stick with *good enough*. Instead of pointing out changes that couldn't be achieved in a certain timeframe, just mention it.

![A change that might be to big.](https://dev-to-uploads.s3.amazonaws.com/i/hum547po2zls5vkk1f81.png)

### Don't hide answers
If you're asking for a certain improvement, tell how it could be achieved. 

![Do not hide improvements. Just say it.](https://dev-to-uploads.s3.amazonaws.com/i/eu2jjw0l4rr90bwk59u6.png)

### Avoid using "YOU" as much as possible
This is a minor one, but remember we're judging the code itself, not its author.

![Avoid using "YOU".](https://dev-to-uploads.s3.amazonaws.com/i/caqjutzheh6cscwqhlpu.png)

## Conclusion
We as developers must contribute to a diverse environment, where different opinions are heard, and discussed respectfully. 
I hope these tips help you all to do better reviews. 

It's ok if you don't agree with all of these. So I would love to hear what you think in the comments. What do you all think?

This is also my first post on this blog, and I hope you've liked it!

Kind regards,
Tancredo.