Comments

Comments

  • Use /** ... */ for multi-line comments. Include a description, specify types and values for all parameters and return values.

    ```javascript // bad // make() returns a new element // based on the passed in tag name // // @param {String} tag // @return {Element} element function make(tag) {

    // …stuff…

    return element; }

    // good /**

    • make() returns a new element
    • based on the passed in tag name *
    • @param {String} tag
    • @return {Element} element */ function make(tag) {

    // …stuff…

    return element; } ```

  • Use // for single line comments. Place single line comments on a newline above the subject of the comment. Put an empty line before the comment.

    // bad
var active = true;  // is current tab

// good
// is current tab
var active = true;

// bad
function getType() {
  console.log('fetching type...');
  // set the default type to 'no type'
  var type = this.type || 'no type';

  return type;
}

// good
function getType() {
  console.log('fetching type...');

  // set the default type to 'no type'
  var type = this.type || 'no type';

  return type;
}

  • Prefixing your comments with FIXME or TODO helps other developers quickly understand if you’re pointing out a problem that needs to be revisited, or if you’re suggesting a solution to the problem that needs to be implemented. These are different than regular comments because they are actionable. The actions are FIXME -- need to figure this out or TODO -- need to implement.

  • Use // FIXME: to annotate problems.

    function Calculator() {

  // FIXME: shouldn't use a global here
  total = 0;

  return this;
}

  • Use // TODO: to annotate solutions to problems.

    function Calculator() {

  // TODO: total should be configurable by an options param
  this.total = 0;

  return this;
}

⬆ Back to Table of Contents