Clean Code Chapter 4: Comments on Comments
In my time studying software development, I have probably written twice as much code as I’ve read. That’s not a humble brag, in fact, exactly the opposite.
My life these days is mostly coding challenges and project building. Aside from skimming Stack Overflow responses to issues and reading the intense and elaborate Python documentation, it’s not that often that I’ll pick up a piece of code and stare at what has been written, or commented, for that matter.
And yet, from what I’ve heard, the life of a software developer (particularly junior devs) involves a lot of reading, reviewing, and testing code.
With that in mind, wouldn’t it be useful to think about the role of comments, and how they can add value to our code? That’s exactly what is covered in Chapter 4 of Clean Code by Robert Martin (aka Uncle Bob).
The author’s philosophy on comments seems to be: the less the better. This is not shocking, and pretty similar to his terse opinions on functions.
This is mostly borne out of a desire to eliminate gratuitous and utterly unhelpful comments. According to Martin, here are a few (crappy) types of comments to keep an eye out for:
- Mumbling, aka comments that are non-sensical or not clear to the average reader.
- Redundancy (Repetition. You know, saying the same thing over and …)
- Misleading comments. Most comments eventually fall into this category as software expands and ages. Comments get separated from the code they’re attached to and changes in functionality make the meaning of comments increasingly more obtuse.
- Mandated comments. Apparently this is something some managers make their employees do? This is for sure not super helpful to keeping comments lean and mean.
So, are there any good comments? According to the author, very few. There are basically three or four reasons that a developer should write a comment, all of which involve anticipating and helping the next developer who comes along to avoid a heap of trouble.
The first suggested comment type is comments to provide information. Comments that explain intent or for clarification, for instance explaining complicated concepts that help to make the code word, are okay (so long as they don’t take up too much room and distract from the real action).
For instance, if there is an obscure or abstract CS concept that is at play which makes a particular function software work, it’s good to mention this so that future devs know what’s up if or when they feel the need to change the code in some way.
Another good reason is to explain intent. If you review your code and think people should understand why you wrote something a certain way, by all means write a comment.
Explaining why you chose a particular strategy and not another might help future devs avoid rewriting the code with false assumptions. This may also help them understand what previous attempts have failed and why. The team will thank you when they’ve saved time!
Another reason mentioned in the book is a solid one, namely if you need to warn of consequences. If, for instance, running a program leads to hours upon hours of migrating files and this is not readily apparent in the code, it might be good to include that detail in a comment (e.g., don’t run this unless you have time to kill….) so people know what they’re getting into.
One last notable exception was legal comments. It’s important to have lawyers, otherwise how would anybody get paid? I guess.
Anyway, it’s for that reason (I can only guess) that Martin thinks legal comments are okay to add to docs as needed.This makes perfect sense and is not really something I’m super concerned with at this moment, but worth mentioning.
Overall, this chapter of Clean Code was super helpful and made me rethink an aspect of coding I had almost taken advantage of. I look forward to tackling the next chapter in the book and continuing on the journey to cleaning up my code!
