A case for code comments?

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 fairytale and code comments are useful. So what's the answer?

The argument against code comments

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:

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."

Is self-documenting code a myth?

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.

So when is it okay to use comments?

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 explains 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...

Tips on writing code comments

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:

1. Use descriptive names

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:

int timeInSeconds

2. Don't comment the obvious

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!"

3. Keep it concise

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.

4. Avoid ambiguous words

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.

5. Don't use jargon

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.

6. Avoid passive voice

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.

7. Avoid slang and dialect words

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!

8. Stick to one language

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:.

9. Avoid location & temporal words

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.

10. Be cautious with humour

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.

Summary

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!).