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 on control structures and functions.
Commenting Control Structures
Space before the control structure is a good place for comments.
We may want to explain why we’re doing something with the loop or conditional statement.
Put a Comment Before Each if, case, loop, or Block of Statements
If we want to put in comments, we should put them before if , case , loops or blocks.
It’s a good place to clarify those structures.
Comment the End of Each Control Structure
We may also want to put them at the end of each control structure.
Treat End-of-Loop Comments as a Warning Indicating Complicated Code
Our loops usually don’t need much explanation.
If we feel like that we’ve to explain it with comments, then it’s probably too complex.
Therefore, we should simplify them in those cases.
Commenting Functions
We don’t need long comments before our functions.
If we have to write to them for every function, then people won’t be willing to create more functions, and rather make the existing ones long and hard to read.
Keep Comments Close to the Code they Describe
We should keep comments close to the code they describe so that they’ll more likely be maintained.
Also, we know what it’s actually commenting on if they’re close to the code that they’re describing.
Describe Each Function in One or Two Sentences at the Top of the Function
One or 2 sentences are enough to describe a function.
If we can’t describe our function in one or 2 sentences, then it’s probably too long.
Except for get and set accessor functions, the rest may use some description.
Document Parameters Where they are Declared
When parameters are declared, then we may want to describe them.
This way, we know what they’re storing if needed.
Comment on the Function’s Limitations
If there’re any limitations that we have to know about, then we should document them so that we know what we may run into when calling it.
Document the Function’s Global Effects
If a function changes global variables, then we should know about that.
It might be hard to find what we’re doing with global variables, so comments may help with that.
Document the Source of Algorithms that are Used
If we used an algorithm from some other source, then we may want to attribute it to that source so that people can look them up in that source.
Use Comments to Mark Parts of Our Program
We may also want to mark parts of our program with comments so we can find them later.
Describe the Design Approach to the Class
If we design a class, then we may want to explain our design approach by leaving some comments in the class.
The design philosophy, ap[approach, and alternatives that were discarded can all be explained.
Describe Limitations and Usage Assumptions
Any limitations and usage assumptions with our class can be explained with comments.
Issues with error handling, global effects, and uses of algorithms can all be explained.
Comments on Files
The top of code files is also good place to put comments.
Describe the Purpose and Contents of Each File
The purpose and content of each file may also use some explanation.
For instance, we can explain why there are multiple classes in a file.
Also, we may also want to explain why we divide our code into files in the way that we did.
Put Name, Email Address, and Phone Number in Block Comments
Name of the author, his or her email address, and phone numbers may be in comments.
However, the name of the author may already be in the source control history, so we may not need it in the comments.
Include a Version-Control Tag
To identify the version of the program built, we may want to add a version control tag automatically to make that easier.
Include Legal Notices in the Block Comment
If a legal notice is required, we may also want to include in a comment in our code files.
Conclusion
There’re a lot of things that we may want to write comments for.
Legal notices, version numbers, design approaches and more can be outlined with comments.
We may also explain the limitations of our code in there.
