JavaScript - Comments




JavaScript - Comments

Comments are an important part of your JavaScript application. While you may easily remember what an application does for a day or two after you write it, trying to figure out what complex applications are doing one or two years later can prove difficult. In fact, there are documented cases where companies have had to rewrite applications from scratch because no one could figure out how the application worked due to a lack of comments. No one has an infallible memory, so comments are an important way for you to keep track of what your application does. JavaScript doesn’t care about your comments. It ignores them, so you can write the comments any way that you want. The content is there to help you. Good comments explain details such as -

  • Why you wrote a particular function or other code block.

  • What task the code block is supposed to perform.

  • Who requested the code block.

  • How the code was created and tested.

  • Who worked on the code (including contact information)

  • Why you used a particular technique for writing the code block,

  • Which resources you used to create the code

  • When the code was created.

JavaScript Single-line Comment

How to create single-line comments in JavaScript, Most developers use what are called single–line comments. A single-line comment can appear anywhere on a line. To create a single-line comment, you type two forward slashes (//) and then the comment text. Here are examples of single-line comments.

function WriteText()
{
  // Change the first statement, then wait so the
  // user can see the change.
  document.getElementById("First").innerHTML =
   "Changed First";
  alert("Check First!"); // Wait here.
  // After the user clicks Click Me, show the
  // change to the second statement.
  document.getElementById("Second").innerHTML =
   "Changed Second";
}

Each line begins with a double slash (//) to indicate that it’s a comment line. Notice that you can begin a comment after the code in a line, as shown in the line with the alert() call in it. Everything after the double slash is treated as a comment.

JavaScript Multi-line comment

A single-line JavaScript comment beginning with double forward slash (//). Following is an example of Single line comment. Sometimes you have more than one or two lines worth of comment to write. In this case, you can create multi-line comments. A multi-line comment begins with a slash and an asterisk (/*) and ends with an asterisk and slash (*/). Here’s an example of a multi-line comment.

<script language="JavaScript">
  /* This function makes changes to the text on the
  * page after the user clicks Click Me as a
  * demonstration of modifying page elements using
  * multiple lines of code.
  *
  * Written by: John Mueller */
  function WriteText()
  {
   // Change the first statement, then wait so the
   // user can see the change.
   document.getElementById("First").innerHTML =
     "Changed First";
   alert("Check First!"); // Wait here.
   // After the user clicks Click Me, show the
   // change to the second statement.
   document.getElementById("Second").innerHTML =
     "Changed Second";
  }
</script>

In this case, the comment is used to create a description of the function. These blocks often appear in team projects to help members interact with each other. For example, this comment would tell someone on the team who wrote the block of code shown in the example.

JavaScript Documentation Comment

A documentation style JavaScript comment you can write following way. It's good habit to write remarks, arguments, notes etc on JavaScript.

<script type="text/javascript">
  /** 
    * ScriptDoc technique to write comment
    * @TagName Description
    * ….
  **/
</script>

A comment is a note written in the code source with the purpose of explaining the code. A single line comment is written in JavaScript as two slashes // followed by the comment itself. A multi line comment is written with a slash and asterisk /*, */, as start and finish tags with the comment in between. Comments can also be used to prevent certain code from running, which is known as commenting out the code. This is useful for testing purposes.

What is a comment?

When programming, it's often useful to be able to document what we're thinking — maybe for someone else who might read the code, or just for ourselves later. We don't necessarily want this documentation to run or influence the code in any way, but we want to add some notes right next to the code for safe keeping. This is where comments come in.

Why comment?

Not only do comments allow us to express the intent of our program in natural language (which is, naturally, easier for ourselves and others to reason about), allowing us to communicate the intent of our program to people who have never seen it before; comments also help us to identify subtle misunderstandings before they become bugs. Think of it this way: often, we feel that we have understood a problem and implemented a good solution. Say we're making a cake, and we want it to be fluffier — we've heard of fluffy omelets, so we think that adding an extra egg or two to the cake might be the solution we're looking for.

But then when we say this aloud — outside of the realm of the recipe and the baking process — we realize that blindly adding eggs to a cake might not achieve the desired result. Our cake's lack of fluffiness is due to something else. Comments work similarly. We might assume that a program works in a certain way, but when we describe how it works aloud (or in comments), we realize that we've misunderstood something fundamental — and now we can correct our misunderstanding before it turns into a bug. Also, you'll see comments throughout the lessons on Learn — we want to make sure that you're familiar with them.