Commenting your code

Commenting your Code

Comments as documentation

Placing comments in your code is a good simple form of documentation. Here is a guide on freeCodeCamp on How to Comment Your JavaScript Code. This contains some good straightforward examples of how to comment your JavaScript code.

Comments are parts of your code that do not execute. The comments are used to make something about the code clearer. You don’t need to comment every line of code, as this just makes your code hard to read. Instead, you make comments on parts of code that you think might be hard for someone else to understand.

Types of documentation comments

Single line comments

A single line comment is created by using the // characters. There is no space between the slashes. If you begin a line with the //, the whole line is treated as a comment. This is because everything after those characters is ignored as far as execution of the code goes. Here is a simple example of using the single line comments:

let x = 7; // initialize x
// while x is positive
while (x > 0) {
  console.log('x is',x);
  x = x - 1; // decrement x by one
}

So, on line 1 and line 5, the comments follow an instruction. So, everything before the // is executed, and everything after the // is not executed. On line 1, the comment is just explaining that we are giving x an initial value. On line 5, we are explaining that we are decreasing the value of x by 1 each time the while loop repeats.

On line 2, that whole line is a comment. This is just a statement that the while loop will continue as long as x is positive.

Block (multiline) comments

Block or multiline comments are comments that go over more than one line. This is a kind of shorthand way of commenting several lines in a row. To create a block comment, you enclose everything in the comment between the starting characters '/*' and the ending characters '*/'. Here is an example:

const nums = [1, 5, 9, 15];
/*
  The following for loop iterates over the nums array.
  It makes use of the index property of arrays.
  The index is an integer in square brackets that follows
  the array name.  So for example:
  nums[0], is looking up the number 1
  and
  nums[2], is looking up the number 9.
*/
for (let i = 0; i < nums.length; i++) {
  console.log(nums[i]);
}
/*
  This for loop will print:
  1
  5
  9
  15
*/

Lines 2-10 and lines 14-20 are examples of block comments. So, the only executable code here is on line 11-13. Note that this is an example of overcommenting the code. Unless the person looking at this code is quite new to programming, they already would know what this code does. So, those comments are not needed. But, besides this fact, this does illustrate how block comments work.

Comments to help debug

Both single line and block comments can be used as an aide in debugging code. You can use a single line comment to prevent a single line from executing if you suspect that the bug is on that line. If the program runs okay after commenting that line out, you have verified the location of the bug. The same thing applies to block comments. If you don’t know exactly where a bug is located, you can comment out entire blocks of code. If the bug disappears after commenting out a particular block, you know the bug is in that block of code. If the bug remains, then you know that the block of commented out code does not contain the bug.

This type of commenting is useful when you have runtime errors. These are errors that only show up when you try to run the program. If you have syntax errors, the program will be stopped from running and you will often get a message that tells you what kind of syntax error you have. So, for syntax errors, you don’t need to comment out code to find them. The compiler or interpreter will let you know that you have a syntax error. But, if you don’t have any syntax errors and the error only shows up when the program is actually running, then that kind of runtime error often is easier to locate by commenting out parts of the code.

JSDoc comments

JSDoc comments are a special kind of block comment that is used to comment a function or module. JSDoc comments can be used by the Node.js package jsdoc to generate formal documentation for a project. Some programmers use JSDoc style comments for their functions and modules even if they are not going to use them to generate formal documentation. This is just because they believe it helps to make it easier for others to make use of those functions and/or modules correctly. But, because JSDoc can be used to generate formal documentation, you must follow the rules for creating proper JSDoc comments if you are going to use them for generating formal documentation. JSDoc comments start with '\**' and end with '*/'. So, compared to regular block comments, there is an extra asterisk for the starting characters. Within that block of comments, you use tags to formally describe the code. Such tags include things like @param and @returns.

Here is a simple example of using JSDoc comments for a function that takes an array of numbers and returns the sum of all the numbers.

/**
  This function returns the sum of an array of numbers
  @param {number[]} array - The array of numbers to get the sum for.
  @returns sum - The sum of the numbers in array.
 */
function getSum(array) {
  let sum = 0
  for (let num of array) {
    sum = sum + num;
  }
  return sum;
}

Here is a screen shot of the kind of HTML documentation that is generated for this example:

The @param tag is used to document all the parameters passed to a function. The parameters are the values separated by commas that are in the parentheses following the function name. The @returns tag is used to document the value that the function returns if any.

Here is another example of a module that contains some classes for drawing 2d objects in a HTML5 Canvas:

/**
 * Represents a filled circle for a HTML5 canvas
 */
class Circle {
  /**
   * Constructor for a Circle
   * @param {number} x - The x-coordinate for the center of the circle
   * @param {number} y - The y-coordinate for the center of the circle
   * @param {number} radius - The radius of the circle
   * @param {string} color - The color to fill the circle with
   */
  constructor(x, y, radius, color) {
    this.x = x;
    this.y = y;
    this.radius = radius;
    this.color = color;
  }
  /**
   * Draws the circle
   * @param {CanvasRenderingContext2d} ctx - The graphics content of the canvas
   */
  draw(ctx) {
    ctx.beginPath();
    ctx.arc(this.x, this.y, this.radius, 0,  2*Math.PI);
    ctx.fillStyle = this.color;
    ctx.fill();
    ctx.closePath();
  }
}

/**
 * Represents a filled rectangle for a HTML5 Canvas
 */
class Rectangle {
  /**
   * Constructor for Rectangle class
   * @param {number} x - the x-coordinate of the left edge of the rectangle
   * @param {number} y - the y-coordinate of the top of the rectangle
   * @param {number} width - the width of the rectangle
   * @param {number} height - the height of the rectangle
   * @param {string} color - the fill color of the rectangle
   */
  constructor(x, y, width, height, color) {
    this.x = x;
    this.y = y;
    this.width = width;
    this.height = height;
    this.color = color;
  }
  /**
   * Draws the filled rectangle
   * @param {CanvasRenderingContext2d} ctx - The graphics content of the canvas
   */
  draw(ctx) {
    ctx.beginPath();
    ctx.fillStyle = this.color;
    ctx.fillRect(this.x, this.y, this.width, this.height);
  }
}

Here is a screen shot of the HTML for the Circle class:

Here is a screen shot of the HTML for the Rectangle class:

So, as you can see, using JSDoc can be used to generate formal documentation.