Commenting those things – Front-end Code Quality series (Part 1)

4.1 [Recommended] Use // for single-line comments

Comments should be written on a single line above the commented object and not appended to a statement:

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

// good
// is current tab
const active = true;Copy the code

A blank line is required above the comment line (unless the comment line is above the top of a block) to increase readability:

// bad
function getType() {  
  console.log('fetching type... ');  
  // set the default type to 'no type'
  const type = this.type || 'no type';  
  return type;
}
  
// good
function getType() {  
  console.log('fetching type... ');  
  
  // set the default type to 'no type'
  const type = this.type || 'no type';  
  return type; } // good // Comment lines above the top of a block do not need a blank linefunction getType() {  
  // set the default type to 'no type'
  const type = this.type || 'no type';					
  return type;
}Copy the code

4.2 [Recommended] Multi-line comments using /**… */ instead of multiple lines //

// bad
// make() returns a new element
// based on the passed in tag name
function make(tag) {
  // ...

  return element;
}

// good
/**
 * make() returns a new element
 * based on the passed-in tag name
 */
function make(tag) {
  // ...

  return element;
}Copy the code

4.3 [Mandatory] There must be a space between the comment content and the comment character to improve the readability. eslint: spaced-comment

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

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

// bad
/**
 *make() returns a new element
 *based on the passed-in tag name
 */
function make(tag) {  
  // ...

  return element;
}

// good
/**
 * make() returns a new element
 * based on the passed-in tag name
 */
function make(tag) {  
  // ...

  return element;
}Copy the code

4.4 [Recommendation] Use special Comments

Sometimes we find a possible bug, but for some reason we can’t fix it. Or there may be some unfinished functionality somewhere, in which case we need to use corresponding special markup comments to inform future partners or ourselves. There are two kinds of special tags commonly used:

• // FIXME: What is the explanatory problem

• // TODO: describe what else TODO or the solution to the problem

class Calculator extends Abacus {
  constructor() { super(); // FIXME: shouldn't use a global here total = 0; // TODO: total should be configurable by an options param this.total = 0; }}Copy the code

4.5 document annotations, such as functions, classes, files, and events, should use jSDOC specifications

Such as:

Constructor * @constructor * @param {string} author - the author of the Book. */functionBook(title, author) { this.title=title; this.author=author; } the Book. The prototype = {/ * * * to obtain the title of the Book * @ returns {string} | * * / getTitle:function() {returnthis.title; }, /** * set the number of pages in the book * @param pageNum {number} page */setPageNum:function(pageNum){ this.pageNum=pageNum; }};Copy the code

There are tools available to ensure annotation quality, such as:

Eslint: Ensures a consistent comment style

ESLint is one of the most popular javascript code checking tools. ESLint has several comment rules that you can optionally enable: