JavaScript is a very forgiving language. It’s easy to write code that runs but has mistakes in it.
In this article, we’ll look at the best practices for commenting code, including what we can comment on.
Commenting Paragraphs of Code
Paragraphs of code may receive comments to clarify them.
Anything that clarifies them and doesn’t repeat the code is good.
Write Comments at the Level of the Code’s Intent
Comments at the same level of the code’s intentions are good.
Therefore, whatever we’re commenting should be right before the code that we’re explaining.
Focus Documentation Efforts on the Code Itself
We should write self-documenting code all the time.
This means that the variable and constants names have to be meaningful.
Likewise, functions, classes, objects, and properties’ names also need to be descriptive.
For instance, we may write the following:
let numApples = 1;
Now we know that the variable above stores the number of apples.
We can do the same for everything else that we have to name.
Focus Paragraph Comments on the Why Rather than the How
We should focus on why we’re doing something in the comments rather than how.
How we do something is already explained by the code, so we don’t need to repeat that in our comments.
Use Comments to Prepare the Reader for what is to Follow
We may also want to tell readers what to expect in our code.
This way, they can read the comments and know what’s going on after the code.
Make Every Comment Count
Comments should be useful. Otherwise, they should be written.
We should focus more effort on making the cod readable rather than writing more comments.
Document Surprises
If we find things that aren’t obvious by looking at the code, then we should document them in comments.
This way, developers working on the code won’t fall into the trap.
Avoid Abbreviations
Not everyone understands abbreviations, so we shouldn’t use them.
Only the most commonly known ones may be used.
Differentiate Between Major and Minor Comments
We may also define different levels of comments.
To do that, we may want to do that with different symbols.
For instance, we can write:
// check strings that are to be deleted
// ... determine number of strings in the table
In the code above, we have the first line defined as major comments and second line as a minor comment as denoted by the ... symbol.
Comment Anything that gets Around an Error
We may want to comment on a workaround that we found in our code.
Also, we can do the same for undocumented features in a language or environment.
However, there shouldn’t be too many of these around.
Justify Violations of Good Programming Style
If we have to violate a good programming style, then we’ve to justify it.
It’ll make everyone know that isn’t being sloppy.
Don’t Comment Tricky Code, Rewrite it Instead
We shouldn’t write comments to explain tricky code.
If we can make them clearer by rewriting them, then we should do that.
This way, anyone else that’ll work on the code will thank us for making their lives easier.
Comment the Units of Numeric Data
If the units of numeric data aren’t completely clear, then we should make them clear by commenting on them.
We can also put the unit in the variable name rather than adding a comment, which is probably better since we won’t have to add the comment.
Comment the Range of Allowable Numeric Values
Restricting allowable values may be done with comments.
However, we should really do that with our code so that we won’t run into issues with processing invalid data.
Comment Coded Meanings
Since JavaScript doesn’t have an enum type, we may want to use comments to explain coded meanings.
We can use comments to explain what each value means.
Comment Limitations on Input Data
If there’re limitations on input data, then we may want to explain them in our comments.
However, we should also handle them in the code so that we make sure the limits are adhered to in the input data.
Conclusion
There’re many things that we may want to comment on, like input limitations and justify violations of good practices.
Paragraph comments should be used for justifying why rather than how we do things.
