Documentation series (3 Part Series)
If there is one topic that divides the developer community, it's whether to use use code comments or not. Some believe code should be self-documenting and code comments are a code smell, a sign of an underlying problem. On the other side of the fence, others believe that self-documenting code is a fairy tale and code comments are useful. So what's the answer?
Supporters of self-documenting code often highlight that "readable" code and that comments that can become stale or out-of-date and misleading as a result. Allen Holub argues that well-designed code that uses descriptive names shouldn't need code comments:
Allen Holub@allenholubComments in your code can be a "bad smell." Code that models the domain, uses well chosen and descriptive names, is written for readability rather than cleverness, needs almost nothing in the way of comments. If the code is so obscure that you need comments, make it less obscure.22:49 PM - 01 Jun 2019
Similarly in this post on code health developers Dori Reuveni and Kevin Bourrillion wrote: "While reading code, often there is nothing more helpful than a well-placed comment. However, comments are not always good. Sometimes the need for a comment can be a sign that the code should be refactored."
Those opposed to self-documenting code believe it's something of a myth and perhaps more a reflection of programmers' hatred of writing documentation:
Along the same lines developer and co-founder of Write the Docs Eric Holscher called self-documenting "the biggest documentation myth in the software industry in this post, arguing that code comments and documentation still have value.
Meanwhile Jef Raskin wrote that while he endorsed the techniques that some programmers claim make code self-documenting, he also argued that these methods cannot provide the documentation necessary for reliable and maintainable code:
"The fundamental reason code cannot ever be self-documenting and automatic documentation generators can’t create what is needed is that they can’t explain why the program is being written, and the rationale for choosing this or that method. They cannot discuss the reasons certain alternative approaches were taken.
The most common scenarios for needing to use code comments is if your code is particularly complex, it's absolutely impossible to make your code self-explanatory or you want to explain why you did something a certain way. Another popular shared principle for using code comments is:
- Code explain the how, code comments explain the why.
As a documentation advocate, I've personally always seen the value in comments, particular for a beginner or junior developer. Code is designed to be read and executed very literally by machines, whereas no two humans are the same. Our understanding is impacted by a whole host of factors including experience, knowledge level and grasp of a particular coding language. Rather tellingly, the PC Magazine definition of "self-documenting code" also comes with this footnote:
It's very subjective [...] what one programmer thinks is self- documenting may truly be indecipherable to another...
So if you're going to use code comments, there are a number of thing you can do to make them as helpful and useful as possible:
Before you even consider using a code comment, check you can't use a more descriptive name. For example instead of using a comment:
int time = ... // Returns time in seconds
You could use a more descriptive name:
If it's obvious what the code does, don't duplicate this in a comment. For example, don't do this:
print "Hello, World!" // Console prints "Hello, World!"
I would try to keep the number and length of comments to a minimum. There is nothing worse than finding a wall of text in someone’s code. Studies have actually found a correlation between sentence length and user comprehensions.
Certain words can create ambiguity in your documentation. Some prime examples of ambiguous words include:
Should: Suggests an action is optional rather than mandatory. For example, "You should do x to make this work". In most cases its better to use the word must instead.
Please: Everyone writes please because it's polite but it makes an instruction sound like a request rather than a requirement. Be rude, don't say please.
This and it: Ambiguous pronouns like ‘this’ and ‘it’ make it unclear what the subject or object of your sentence is. Always clarify if you can.
Don’t use jargon or acronyms that not everyone will understand. Sometimes we get so caught up in our work, it’s easy to forget what is a common, everyday language for you, might be completely alien to someone else.
For example, instead of writing an acronym write it out in full the first time your write it. For example: Java virtual machine (JVM), Kubernetes (K8s), JSON Web Token (JWT) etc.
Passive voice creates questions and ambiguity. Always include the subject that is performing the action if possible. For example:
- ❌ Passive voice: "The web service is queried." What is sending the query?
- ✅ Active voice: "The user queries the web service." It is clear what the subject of the sentence is.
Using slang or dialect in code comments is likely to cause confusion.
For example, a British developer might write:
\\ Sorry, I wrote this code when I was knackered so it might be rubbish.
In this case, dialect words like 'knackered' (tired) and 'rubbish' (garbage or trash) might not make sense to English speakers from other countries let alone non-native English speakers!
Don’t write in multiple languages. Most people might understand common Latin words but not everyone will understand them so think about using friendlier alternatives:
- e.g.: Use For example, instead.
- i.e: Use that is instead.
- N.B: Use Please note or Note:.
Time never stops and the location of code may change at some point in the future. As a result, it's best to avoid the following:
- 🗺️ Location words: Above, below.
- 🕰️ Temporal words: New, latest, current, up-to-date.
Everyone likes a joke every now and then. Wouldn’t life be boring if we lost our sense of humour? I found this example of humour on Stackoverflow:
stop(); // Hammertime!
While this is funny if you know the MC Hammer song, it’s worth bearing in mind some people won't find this funny if they don't understand the cultural reference. A comment like this may well end up confusing or annoying some people.
If you skipped to the end, in summary... although some people are advocates for self-documenting code, others think code comments can be useful if your code is complex or if you feel the need to explain why you did something a certain way. In my opinion:
Using code comments > Writing code people can’t understand
If you are going to use code comments, my tips include:
- Use descriptive names.
- Don't comment the obvious.
- Keep it concise.
- Avoid ambiguous words.
- Don't use jargon. Define acronyms if you do.
- Use the active voice where possible.
- Avoid using slang.
- Don't write in Latin.
- Avoid location/temporal words.
- Be careful with humour (probably best to avoid!).