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.
Keys to Effective Comments
Wrong comments should be removed. They’re misleading and may lead to developers making wrong decisions.
If they’re just a repeat of the code, then they should definitely not be written.
If there’re any tricky parts of the code that needs explanation, then we may need comments to explain them.
Markers shouldn’t be left in the code. If we use markers to mark defective code that should be fixed, then we should just fix the code.
Summaries of code are better than just repeating code since it lets us look for information more easily with the code.
If a piece of code describes the code’s intent, then it might be useful since it probably isn’t clear from just reading the code.
Information That Cannot Possibly Be Expressed by the Code Itself
Information like copyright can’t be written in the code itself. Therefore, we may need comments to explain them.
Comments that are used for generating documentation are also helpful.
Commenting Efficiently
Commenting shouldn’t be a time-consuming task. Too many or too few comments are both bad.
We got to achieve a middle ground.
If we’re using a tedious commenting style, then we should simplify it.
Words that describe what the program is doing also may not be easy to come by.
Use Styles that don’t Discourage Modification
We should make our comments easy to maintain just like our code.
For instance, if we’re making an elaborate table with comments, then we should consider simplifying that so that others won’t have to update it.
If we use asterisks to delimit comments, then we should reduce those.
Use the Pseudocode Programming Process to Reduce Commenting Time
We can outline code by writing them with pseudocode first before converting them to English.
Integrate Comments into Our Development Style
Leaving comments until the end isn’t a very good habit.
We’ll probably forget to do them and it becomes its own chore.
By the time we finished our code, we probably already forgot about the assumptions and decisions that we want to comment on.
Therefore, we should just comment as we code to make our lives easier and before we forget what to write.
Performance is not a Good Reason to Avoid Commenting
Comments increase code file size, but compilers and interpreters ignore them, so the performance hits are negligible if there’s any.
Optimum Number of Comments
We should just comment as much as we need to and forget about an optimum number of comments.
Avoid Self-Indulgent Comments
We shouldn’t write comments just to express our feels in the code.
No one really cares and they take up valuable space.
Endline Comments and Their Problems
Endline comments don’t align to the right side of the code since it’s hard to do so.
Also, we’ve to move our cursor all the way to the right to add or edit the comment.
Therefore, they’re hard to maintain and most people won’t want to touch them.
If they’re on the right, then people writing the comment have to make them short to keep the line lengths short.
Therefore, there isn’t much benefit to keeping them on the right and lots of problems.
Avoid Endline Comments on Single Lines
We shouldn’t comment on every line of our code. And we shouldn’t have them on the right.
There’s not that much to write about for one line of code.
Avoid Endline Comments for Multiple Lines of Code
Our comments probably won’t fit at the end of the line.
It’s just a bad place for comments.
Use Endline Comments to Annotate Data Declarations
Data declarations can have comments placed on the right of them.
These lines are usually short, so there’s space for comments to the right.
Avoid Using Endline Comments for Maintenance Notes
Since we’re supposed to be using version control systems for storing code, maintenance notes belong to the commit comments.
Therefore, keep them out of the code files.
Use Endline Comments to Mark Ends of Blocks
If we have long blocks, then we should mark the end of blocks with end line comments.
This way, we know where’s the end of each block is.
Conclusion
Comments can be tricky. We shouldn’t use them to repeat our code or commit comments.
Also, comments at the end of a line should be used sparingly or short lines.
Comments should also be easy to maintain so that we’ll be willing to update them.
