Creating maintainable JavaScript code is important if want to keep using the code.
In this article, we’ll look at the basics of creating maintainable JavaScript code by creating better single-line comments.
Comments
Many people don’t like comments.
They’re a chore to add and update.
And they feel like documentation.
Fortunately, the code serves as our documentation most of the time.
We can just write some comments to cover things that haven’t been covered by the code.
JavaScript supports 2 kinds of comments.
A comment can be a single line or multiline.
Single-Line Comments
A single-line comment starts with 2 slashes and ends at the end of the line.
For instance, we can write:
// a single-line comment
to add a single-line comment.
We usually add a space after the 2 slashes to offset the comment text.
Single-line comments can be used in a few ways.
They can be used in their own line to explain what’s following the comment.
The line should always be preceded by an empty line.
The comment should be at the same level of indentation as the following line,
We can also use them as a trailing comment at the end of a line of code.
Therefore should be at least one indent between the code and the comment.
And the comment shouldn’t go beyond the max line length.
This avoids any kind of horizontal scrolling just to read the comment.
If the comment needs to go into the next line, then we should put the comment in its own line above the code.
We can also use comments to temporarily stop a piece of code from running by commenting them out.
This can be done automatically with many text editors.
Single line comments shouldn’t be used on consecutive lines unless we’re using it to comment out code temporarily.
For instance, we can write:
if (condition) {
// all permission checks are successful
allowed();
}
We have an empty line above the comment to improve readability.
This is better than:
if (condition) {
// all permission checks are successful
allowed();
}
which is harder to read because of a lack of blank lines.
The indentation is also important.
It should be at the same level as the code we’re commenting on.
So we shouldn’t write comments like:
if (condition) {
// all permission checks are successful
allowed();
}
Also, we should add some spaces between a piece of code and the comment if they’re on the same line.
For example, we write:
var result = count + anotherCount; // both are always numbers
This way, we have a space between the code and the comment.
We shouldn’t write something like:
var result = count + anotherCount;//both are always numbers
since there’s no space between the code and the comments.
Also, we shouldn’t write comments like:
// a condition that checks for
// all permissions.
// If all permissions are present,
// then we do something
if (condition) {
allowed();
}
We have multiple single-line comments, which should be a multiline comment instead.
Conclusion
There are better ways to write JavaScript comments than others.
Single-line comments can be formatted better with spaces and the correct indentation.
If a single-line comment is too long, then it should be a multiline comment.
