Summary – Code comments that point out the obvious make the important comments harder to spot. Developers are better off when there are only a few comments for the code that deserves an explanation.
You open up an electrical box and see a few hundred wires. Lots of different colours that don’t mean a heck of a lot. But someone has put a neat little label on every wire. Awesome!
Or so it seemed until you actually start looking at the labels. Almost all of them are blank!
So you spend an hour digging through every label. In the end, you find a total of 12 actually written with an important message. Hopefully you didn’t miss any in all the chaos.
This is how I feel when I dig into code with useless comments everywhere. It’s hard to identify useful comments in the sea of useless ones. Needles in a stack of needles.
Here’s a great example that shows up everywhere in a very popular open source project:
/**
* __construct function.
*
* @access public
* @return void
*/
public function __construct() {
...
}
And another one…
/**
* Constructor
*/
public function __construct() {
...
}
And here’s another gem…
// Convert float to string $value = float_to_string( $value );
These comments are similar to the blank labels in the electrical box. They point out the obvious, add noise, and diminish the overall usefulness of commenting. After reading a few of these comments, I wouldn’t blame any developer for ignoring the rest.
I’m sure the electrician that took the time to put blank labels on each wire thought he was doing a great service to those who would come after him. After all, the label is already there, they just have to write the note now. Or maybe he had intended to fill in all the labels, but never got around to it. Regardless of his good intentions, the result is a much worse situation than if he had only labelled the 12 wires.
In the coding world, developers are told they should always comment their code, but rarely are they told how to do so. And so comments are often written because developers feel an obligation to do so, not because a comment is needed. They feel they are doing their job well if they add lots of comments, regardless of their quality.
I can’t accept this. I would much rather see a few comments explaining why some code is needed than a comment on every few lines that say nothing. Comments shouldn’t be written purely to show we’re “good little programmers.” We should use comments sparingly and mainly to “document the why”.
// We need to account for product price changes, // so we get the price of the product when each order occurred $order_prices = $this->get_order_prices();
When deciding if I should write a comment or not, I ask myself a simple question: if I come back to this bit of code, will it be obvious why it’s been written this particular way? If my future self will be very thankful for an explanation, then it’s a no brainer, I write the comment. Otherwise, I let the code speak for itself.
Further Reading
- Document the Why by Ian Lotinsky (2013)
- Code Tells You How, Comments Tell You Why by Jeff Atwood (2006)