Stray Thoughts Run Amok

Don’t Leave Comments On Your PR

I’ve seen this happen a few times recently so I feel the need to call this out for my fellow developers.

Don’t leave comments on your pull requests.

Don’t get me wrong, you absolutely should respond to peers seeking clarification about the code you wrote. And sometimes you might see an area that you know is going to spark questions and you preemptively describe it. That’s all good.

But what isn’t good is leaving those comments in your pull request system. Where they really belong is in your code right next to the part that you’re explaining. This is the best way to preserve those comments and help out your team.

This might seem unimportant to some people, it might seem like an unnecessary step. For someone who’s been in the industry for a while let me tell you something that you might not have considered. You might not be using the same version control host in five years. You might think this is impossible especially if you’re with one of the bigger hosts. But trust me, I’ve spent enough time in the industry to experience times when teams had to move from one VCS host (and even complete systems) to another. When you need to make this move, the less that you have to pull out of your VCS host, the easier it is.

There’s another, perhaps greater, reason why your comments should not just be in the PR and that is because it is clearly needed to explain something to the next person. Even if your current VCS host lasts forever, it is so much easier to read a comment explaining how a piece of code works when you’re looking at that code. Searching, hoping that you can find some random comment to help explain why something was done is frustrating and often fruitless.

So do yourself and your team a favor and don’t leave your comments on your PR.