The principal I go by here is something I heard a long time ago. Code is read far more often than it is written. That bit of code you are writing today will potentially be read thousands of times in the coming years. Even if it takes a few more minutes to make it readable, the impact on maintenance can be absolutely enormous.
Today I had a senior developer ask a question in our slack #engineers channel asking about the difference between making comments in code or in a pull request. Here are my thoughts.
TL;DR
Comments in the code help other developers understand what a piece of code does, while comments on the PR help the reviewer understand why a piece of code was needed to accomplish the task at hand.
Comments in Code
In Ruby, comments in the code shouldn't be needed very often, as Ruby code should be mostly self-documenting. What I mean by that is it should be well named and easy to read. Class names, method names and variable names should be applied so that when they are read they explain what they do or what they are for. When this happens, code is self-documenting.
That said, there are times when it may not be obvious what a bit of code does. When this happens, comments in the code help give clarity to whomever is reading the code. This can happen because of hidden system dependencies (think vendor interactions, callbacks or state machine interactions as just some examples) or even for other reasons. As developers, we should know when a piece of code should make sense when it's read. When it doesn't, it should be refactored when possible, or commented when not.
The principal I go by here is something I heard a long time ago. Code is read far more often than it is written. That bit of code you are writing today will potentially be read thousands of times in the coming years. If it takes a few more minutes to make it readable, the impact on maintenance can be absolutely enormous.
Comments in the PR
These comments are different. There are many times when a piece of code is perfectly readable, but it's not obvious at all why it was added in this PR.
When I am doing a code review, I am looking at a ticket and see what bit of work is being asked for. If it's not obvious why a code change was needed, that's the perfect place to add comments in a PR. Always err on the side of something not being obvious. In other words, if you aren't sure if it's obvious, leave a comment in the PR to be certain.
These comments wouldn't make sense inside the code, because when reading the code it doesn't matter what particular thing it was meant to solve at the time, only that it's easy to understand what it does.
These comments also have a big impact, when it comes to time saving. With good comments on a pull request, there is much less back and forth for code review.
Even more, imagine you are looking at a bit of code and you aren't quite sure what problem it was meant to solve in the first place. You git blame and find out who added the code and what the commit was, and then you use that to get back to the original pull request where it was merged. Now imagine the developer had added some comments in the pull request that indicated what the thinking was behind the change. How much easier would that make your day today?
Top comments (0)