While naming variables, functions and classes is one of the hardest things to do as a programmer, writing comments is also hard. It’s easier to express our logic in code vs English. Let’s look at the best ways to write comments in code.
YAGNI — You aren’t gonna need it
Try to write code that does not need comments as I mentioned before, it's easier to express logic in code vs English. Try to make your code as boring as possible. Do not be clever. The clever you get, the harder it might be to understand the rationale behind your code after a few months.
Best comments are the ones that are not required to be written in the first place
We often make the mistake of explaining what the block of code or the next line of code DOES rather than WHY we did that. So if your code is so obvious, you wouldn’t need a comment. If it's not so obvious, then you should explain WHY you did what you did.
Remember, explain WHY.
Avoid ambiguous terms
Since English is quite diverse, it's easy-to-use words that confuse more than explain. Whenever you use a word, think critically, if the word makes sense to the person who might read your code 6 months later. Avoid introducing words that mean the same.
For example, your function’s name is getUsers and to explain you write a comment like Fetches the list of users
It would have been better to use gets the list of users or better yet, don’t use comments at all as the name of the function is good. (That's why naming is the hardest, but if you get it right, you wouldn’t need comments)
If your function is being used elsewhere, or if the function is a part of a bigger function, we might often try to mention that in the code. However, since the code changes often, that comment might become irrelevant. It's possible that the name of the other method has changed and now the comment is confusing the reader more than explaining.
Try to ONLY talk about the block of the code you want to explain instead of talking about HOW the block of code is used elsewhere.
Do not assume English terms are enough to explain domain related concepts and their processes
Most of the times in our code, the variable names we use might not be equivalent to their real meaning in English. We even invent new words in our codebase. So it's important that when we write comments we directly refer to our domain language or domain related concepts to explain the code better. By domain language, I mean the library of variable names that you have used across your codebase.
We might start our comments like — This code does ….
Or we use “this” word commonly in English, however in code, this has many meanings and different developers can interpret differently the meaning of this. Instead, use the “subject” / variable names directly.
Do not add noise to what you already explained. (Say things once)
When we try to convince someone, we explain the same thing in different ways. We should avoid doing that while writing comments. Write the comment once. Do not duplicate your explanation, as that would only lead to more confusion. Explain the logic in the most succinct manner.
Use active instead of passive voice
I think this is pretty common in English and you can find a lot of resources online to understand how to do this. I would also suggest using Grammarly or ProWritingAid software to help you convert passive to active as they detect this easily.
The reader is usually a programmer, so avoid explaining things that are “reasonably” well understood.
For example, you don't need to explain what an API is or what a webhook is. A developer reading the code would know this already. Most of the times using a technical term or a domain language is faster and easiest way to put your explanation across vs. trying to explain them in plain English.
The code we write could often be very complex with couplings, and it might be easy to explain the complete code in a single multi line comment at the top of the function or block of code. However, when you do that, make sure you explain every information that is crucial to the code to work properly. If you miss a single detail, the reader will have to spend many hours or worse, they might assume something that's completely wrong. First, avoid getting into this situation at all, but if you are in this situation, spend a lot of time thinking about the comment.
Just like we write code with a structure and logic, write your comments as if it was a procedure. For example, food recipes. They do not introduce conversational language and are more understandable by the reader for a long time.
