No comment code

My last post mentioned No Comment Code and my initial horror at the idea. I’d not come across it directly before last year. However I think I’ve seen it’s influence on some other developers. I’ve done a bit of research but will be using Don’t Write Comments and To Comment or Not to Comment as my primary references here.

What they say

There doesn’t seem to be a unified No Comment Code methodology just a general feeling that comments have problems. That has lead some people to write (almost) no comments and others to limit their usage. There also seems to be a distrust of existing comments so they don’t bother to read them.

Their problems with comments are:

1. Writing comments takes time but does not influence runtime behaviour.
2. Comments cannot be tested and therefore may be wrong.
3. Comments are often not properly maintained and therefore may be wrong.
4. Comments may be unrelated or offensive.

Their solution to this is to avoid or limit the usage of comments and let the code speak for itself:

1. Code should be simple to understand.
2. Use well named functions and variables to explain operation.
3. Break functions and expressions down into simple parts.
4. Use explicit types to show what data is.
5. Don’t comment when the code can show what is needed.
6. Do comment to highlight exceptional circumstances, e.g. thread safety, class states, error conditions, non-obvious performance optimisations, references to underlying algorithms.
7. Provide class or API documentation.

My response

Despite my horror they’re not wrong about the problems. I’ve experienced all of these on my projects except the last. I know that one happens as well.

I am in favour of coding being written to be easy to understand. Breaking down large functions into smaller ones and choosing the right name help everyone. Using higher level types rather than basic types adds extra information and can let the compiler check your work. If you have a choice between gaining a little bit of speed or a little bit of clarity I’d recommend the later (unless this is a specific performance bottleneck). However seeing problems with some comments and deciding to throw them all out seems to be an overreaction.

While comments can be wrong I think their solution suffers from the same problem. Here’s an example starting with the commented form:

    // Is letter is a vowel?
    if (std::range::contains({ 'a', 'e', 'i', 'o', 'u' }, letter))
    {
        ...
    }

Then the uncommented form:

    const bool isVowel = std::range::contains({ 'a', 'e', 'i', 'o', 'u' }, letter);
    if (isVowel)
    {
        ...
    }

In both cases I can imagine a commit that changes the search but fails to update the comment or identifier:

    const bool isVowel = std::range::contains({ 'a', 'e', 'i', 'o', 'u', 'y' }, letter);
    if (isVowel)
    {
        ...
    }

With every code change the comment or identifier should be reconsidered but it might not be. It’s something developers should watch for in their own code and code review could be used to help with this. We can’t automatically test the correctness of comments or identifiers. If there’s a mismatch between the code, comments or identifiers then it’s time to look at the commit history.

My main worry about No Comment Code method is that many people will read the headline and stop there. The extra steps to write “better” code will be missed, forgotten or just not done very well. Trying to read “standard” code without comments is hard work. Things are done for unknown reasons and build towards unclear result. Even if you can figure out what is happening it may not be what is meant to be happening. Without comments there is nothing else to check your reasoning against. Letting developers skip comments seems more risky than just bad comments.

I have had a problem with too many comments being used for non-comment purposes. Documentation comments can be helpful but they can easily end up taking up so much space that they distract from the code. Having a few lines to describe a function is fine. However when each parameter, the return value and each related function is mentioned isn’t not. Tests can also be embedded in comments in some projects. Having tests is great but they can end up being much larger than the code they are testing. In both cases the presentation is a big part of the problem. In all editors I use the comments are shown in the same style whatever they’re actually for. Are there any languages out their that support documentation or tests directly? Python has Docstrings but, again, those are just re-using an existing language feature to add documentation.

On balance

Writing high quality code is always a good goal but comments can help:

• Explain why something is done.
• Give the context for the code.
• Summarise sections of code.
• Reference full descriptions of specific algorithms.

I’ve read a lot of code over the years and too many comments has rarely been my main problem.