[Airbnb JS Style Guide] 주석을 사용해야한다면 어떻게 사용해야할까?

우아한테크코스의 자바스크립트 스타일 가이드는 Airbnb 자바스크립트 스타일 가이드를 기준으로 하기에

Airbnb 자바스크립트 스타일 가이드 기준을 보고 이해를 바탕으로 필사하였으며 경중에따라 가감하였습니다.

 

 

함수/변수/클래스명 등 이름만 보고 이해할 수 있을 정도로 의미있는 이름으로 명명하고 최대한 주석은 지양해야하지만 

꼭 필요한 경우는 적재적소에 사용해야한다 

그렇다면  그런 상황이 온다면 어떻게 사용해야 할까 ?

 

 

주석 (Comments) 

1) 여러 줄에 걸친 주석을 쓸 때는 /** .... */ 을 사용하세요.

// bad
// make()는 전달된 태그명을 기반으로
// 새로운 요소를 반환한다. 
//
// @param {String} tag
// @return {Element} element
function make(tag) {

  // ...

  return element;
}

// good
/**
 * make()는 전달된 태그명을 기반으로
 * 새로운 요소를 반환한다.
 */
function make(tag) {

  // ...

  return element;
}

 

 

2) 한줄 주석을 쓸 때는 // 을 사용하세요. 주석 전에는 빈 행을 넣어주세요

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

 

 

3) 모든 주석은 공백으로 시작해야 합니다.

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

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

// bad
/**
 *make()는 전달된 태그명을 기반으로
 *새로운 요소를 반환한다.
 */
function make(tag) {

  // ...

  return element;
}

// good
/**
 * make()는 전달된 태그명을 기반으로
 * 새로운 요소를 반환한다.
 */
function make(tag) {

  // ...

  return element;
}

 

4) 문제지적 or 해결책제안

문제를 지적하고 재고를 촉구하는 경우나 문제의 해결책을 제안하는 경우 등에는 주석 앞에 FIXME 나 TODO 를 붙임으로써 다른 개발자의 빠른 이해를 도울수 있습니다. 이런 것들은 어떤 행동을 따른다는 의미로 통상의 주석와는 다릅니다. 행동이라는 것은 FIXME -- 해결이 필요 또는 TODO -- 구현이 필요 를 뜻합니다.

 

5) 문제에 대한 주석으로 // FIXME:를 사용하세요.

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

    // FIXME: 전역 변수를 사용해서는 안 됨
    total = 0;
  }
}

 

6) 문제의 해결책에 대한 주석으로 // TODO:를 사용하세요.

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

    // TODO: total은 옵션 파라메터로 설정해야함
    this.total = 0;
  }
}

 

 

 

 

source : https://github.com/Ryan-Dia/javascript-style-guide#comments--fixme