JavaScript Comments For Collaboration And Debugging

JavaScript Comments: Clarifying Your Code

Like most programming languages, JavaScript has comments, which are text passages that are a part of a program but are totally disregarded by the JavaScript engine or the computer. They act as notes that help human readers understand the code’s intent and reasoning, providing information that the raw code would not. You can integrate related ideas as part of your program, explain things in normal language, or leave reminders for yourself or other people who might use your code in comments.

Commenting your code is thought to be a good idea. A proficient programmer is distinguished by well-commented code, which also makes it much simpler for anybody viewing your code including your future self to comprehend what is going on. Though they shouldn’t be essays, comments should be enough to make the purpose of the code clear.

Single-line and multi-line comments are the two comment formats supported by JavaScript.

Single-Line Comments

Single-line comments begin with two forward slashes.
JavaScript parsers and engines ignore everything following // until the end of the line as comments.
A statement that is just one line long can take up a whole line.
It can be an inline comment describing a code line at the end.
Since the comment is immediately closed at the end of the line when using //, there is no closing tag.
It is advised to use a space to separate code from an inline comment and to separate the two slashes from the comment content for better readability.
Any number of successive single-line remark lines is acceptable, but they must all start with //.
The most popular approach is said to be the usage of one-line comments.

// This comment occupies a line of its own 
let accountBalance = calculateBalance(account); // It's a green hollow where a river sings 
var animals = []; // Declare an empty array
alert('World'); // This comment follows the statement

Comments in Multiple Lines

Many programmers use a different approach that uses multi-line comments when a comment needs more than one line.

A forward slash and an asterisk (/*) are used to begin multi-line comments, and the same is used to end them (*/).
Everything that comes between the first /* and the last */ is either ignored or not executed.
These remarks may take up several lines.
Multi-line comments in JavaScript (/*… */) have the same syntax as CSS comment tags. Keep in mind that // comments are not supported by CSS.
Nested multi-line comments (/*… /*… */… */) will result in an error because they are not supported.

/* When a comment requires more than one line,
a block comment like this, with its opening and closing tags, is the way to go. */ 
/* This is yet another comment.
* It has multiple lines.
*/ 
/* I'm a multi-line comment.
Whatever is between the slash asterisk and the asterisk slash will not get executed.
console.log("I'm not logged, because I'm a comment"); */

Applications and Optimal Techniques for Comments

There are several uses for comments:

Code execution prevention: This technique, which is helpful for testing or experimenting with different options, temporarily disables a section of code while the script is running.
Metadata: Including information about the file, such as the author.
Explanation: Providing clarification on certain code segments, elucidating the situation, or defending a particular decision. Block comments are the norm for official material.
Reminders: Making notes about future tasks for yourself or other people.

Although leaving a remark is crucial, there are rules for doing it properly:

Instead of just summarising what the code does, comments should ideally explain the rationale behind a certain solution or why it was selected.
Purely “explanatory” comments that describe obvious code actions should be kept to a minimum in well-written code. The code itself need to be straightforward and self-explanatory.
It might be preferable to change the code to make it simpler if it is so ambiguous that a remark is needed to describe what it does.
Well-written comments can explain key solutions that are not immediately apparent, function usage, or the general architecture or high-level view.
It’s also beneficial to comment on subtle and counterintuitive aspects.
Well-written comments facilitate efficient code maintenance and make it simpler to revisit after a break.
The overall code footprint is increased by comments, but since minification tools eliminate comments prior to deployment, this is usually not a problem for production applications.

Uses of Special Comments and Associated Ideas

JSDoc: This system uses special block comments that begin with /** to document JavaScript code. Documentation generators such as JSDoc 3 parse JSDoc comments to produce HTML documentation. JSDoc comments are also used by several code editors to offer code inspection and autocompletion.

HTML Comments in <script> Tags: In older code, you might see HTML comments (<!– and –>) inside <script> tags. This was a technique used to hide JavaScript code from very old browsers that didn’t understand the <script> tag. This is not modern practice. The JavaScript interpreter generally ignores the HTML closing comment –>. An HTML closing comment (–>) at the beginning of a line (optionally preceded by whitespace) can also cause the rest of that line to be ignored in JavaScript. This behaviour was sometimes exploited in clever ways.

DOM Representation: In the Document Object Model (DOM) tree that represents an HTML document, comments (including HTML comments) are represented as Comment nodes. Comment nodes have a nodeType property with the value 8. The text content of a comment node can be accessed via its data or nodeValue properties. Document can programmatically construct Comment nodes.createComment(). Text and Comment nodes cannot be parent nodes in the DOM tree.

JSON: Conventional JSON does not accept comments, unlike JavaScript. JSON comments invalidate it. JSON, a standalone package, permits comments.

Semicolons: While not strictly a comment, semicolons ( ; ) are important for separating statements in JavaScript. Although often optional when statements are on different lines, it is generally considered safer, especially for beginners, to end most statements (those not ending with a curly bracket) with a semicolon. Missing semicolons are a common programming error.

In summary, comments are vital for making code understandable to humans, despite being ignored by the JavaScript interpreter. JavaScript offers single-line (//) and multi-line (/* … */) comment styles, each suitable for different situations. Using comments effectively by explaining the ‘why’ and clarifying complex parts significantly improves code quality and maintainability.

Page Content

Tutorials