Serials Javascript Style Guide – Comments

Comments

Multiline

Sử dụng /** ... */ khi comment nhiều dòng.

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

  // ...

  return element;
}

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

  // ...

  return element;
}

Singleline

Sử dụng // khi comment 1 dòng. Đặt comment phía trên đối tượng cần comment. Đặt 1 dòng trắng trước khi comment trừ phi nó là dòng đầu tiên của block.

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

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

// 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;
}

// also good
function getType() {
  // set the default type to 'no type'
  const type = this.type || 'no type';

  return type;
}

Spaces

Tạo khoảng trắng trước khi comment sẽ giúp dễ đọc hơn. 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;
}

Actionitems

Đặt trước comment các từ như FIXME or TODO giúp cho các lập trình viên khác hiểu nhanh hơn mục đích dòng code đó. FIXME: -- cần xem xét lại hoặc TODO: -- cần cải thiện.

Fixme

Sử dụng // FIXME: để chú thích các vấn đề hoặc nghĩ đó là bug

class Calculator extends Abacus {
  constructor() {
    super();

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

Todo

Sử dụng // TODO: để chú thích các giải pháp cho các vấn đề cần sửa.

class Calculator extends Abacus {
  constructor() {
    super();

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

Tổng hợp Serial Javascript Style Guide