Maxims of comments?

Several years ago Tom Scott made a video, The Hidden Rules of Conversation, which introduced me to the cooperative principle. They are the conventions that are generally followed by everyone in order to communicate effectively. I wonder if they can tell us anything about writing comments?

Grice’s maxims

Paul Grice was writing about the gap between natural language and logical formalism. There can be a big difference between what we literally say and the meaning that someone else takes from that. Ironically he was writing about it in a very formal way which sometimes makes it less clear. He came up with four guidelines:

Maxim of quantity

Be informative.

Specifically:

1. Be as informative as is required for the purposes of the current exchange.
2. Do not make your contribution more informative than is required.

Maxim of quality

Be truthful.

Specifically:

1. Do not say what you believe is false.
2. Do not say that for which you lack adequate evidence.

Maxim of relation

Be relevant.

Specifically:

1. Do say all the information is relevant to the current exchange.
2. Do not say any irrelevant information.

Maxim of manner

Be clear.

Specifically:

1. Avoid obscure language.
2. Avoid ambiguous language.
3. Be brief.
4. Be orderly.

Commenting code

How might these maximums interact with commenting code?

The easiest is probably the maxim of quality. Don’t lie or deceive in you comments, that sounds good. I suspect most of us avoided that anyway. We might not always be as careful if we simply lack evidence. If you think something is the case but don’t know it then it might still be worth saying “think” or highlight the uncertainty. For me that’s a better option than staying silent or over committing. Maybe you could do some more research to confirm, which would be great, but maybe you can’t. There might not be time or you may not have access to the resources you need. If there is a potential issue then noting it means that the uncertainty might be cleared up in the future. Just staying silent means that, good or bad, it’s gone.

Next the maxim of relation. Keep on topic, that is comment about the code and leave everything else out. To me this seems obvious but I’ve seen stories. Comments shouldn’t be about:

• The sort of day you’ve had.
• How terrible your boss, company or colleagues are.
• How great a coder you are.
• Annoyance at having to use terrible libraries.

These may all be true but they are a distraction and so make the comments worse.

The rest probably need some more context. Our situation is slightly different from a conversation, who are we talking to?

• Our future self.
• A team member.
• A future team member.
• Someone on a different team entirely.

Whoever it is I think you should assume that the reader of the comments knows less about the system than you. This may sound obvious but comments are often written just after you’ve written the code. It’s the point that you’re most familiar with it. Your future self will have forgotten at least some of the details and everyone else hasn’t seen it before. They might know some of the background for it or they might not.

Given that we can think about the maxim of manner? We should avoid obscure or ambiguous language. I can think of a few sources of this:

• Algorithms can have their own terminology, e.g. nodes and edges for graph algorithms. If it’s a know algorithm, especially if it’s a specific one you cribbed from, give a reference link to the algorithm. Using the terminology seems okay but maybe explain how it applies in your case, e.g. explain what your nodes and edges are.
• The field the software has been written for, e.g. accountancy software will have lots of taxation terms. This is common and there could be a lot of it them, it can be unavoidable. I think acronyms are the most problematic. Try to have the full expansion of the acronym somewhere the same as you’d have at the beginning of a document.
• The codebase itself might have developed some. I’d stick to my recommendations for good names, stick to understandable words. It’s better not to invent things but if you do then make sure they’re explained.

Try not to leave the reader in the lurch. Right now you know what this means but someone else has to be able to find out.

To me the maxim of quantity is the most interesting one to consider. This is where the No Comment Code movement would often say the code should be self explanatory and so comment free. I largely rejected this. Ideally code should be easy to understand, sometimes it can be but sometimes it just isn’t. However code can be simple enough that certain comments are pointless according to this maxim.

    // Increment count.
    count++

This comment adds nothing to someone’s understanding of the code and should be discarded. However something else, even a longer comment, might be appropriate as long as it adds information.

    // Track the count so we can calculate an average later.
    count++

Of course, if you have a short function then this calculation might be obvious and so make the comment unnecessary again.

If code does something immediately obvious or entirely normal then it can and probably should be uncommented. However some single lines could benefit from a comment and more lines are more likely to benefit. To me comments can help:

• Explain why something is done.
• Give the context for the code.
• Summarise sections of code.

This is a balance, you should provide enough for someone to easily understand the code and then stop.

In the end

A conversation has the definitely advantage that you know more about who you’re talking to. There is a back and forth that narrows down the requirements. Without that we are left somewhat guessing. If you’re writing to a knowledgable colleague then all sorts shortcuts or technical language might be appropriate. If you’re writing to a newly hired developer living 5 years in the future they you need to keep it simple.

Maybe what we really need is an entirely new set of maxims just for comments.