주석 (Comments)

주석은 필수적인 것이 아니다

주석을 굳이 달아줄 일이 없다면 사용하지 않아야한다.
코드만으로 우리의 의도를 표현하지 못할때 주석을 사용하기 때문에, 주석은 필요악이다. 좋은 코드는 그 자체만으로도 좋은 코드가 되어야한다.

나쁜 예

function hashIt(data) {
  // 이건 해쉬입니다.
  let hash = 0;

  // lengh는 data의 길이입니다.
  const length = data.length;

  // 데이터의 문자열 개수만큼 반복문을 실행합니다.
  for (let i = 0; i < length; i++) {
    // 문자열 코드를 얻습니다.
    const char = data.charCodeAt(i);
    // 해쉬를 만듭니다.
    hash = ((hash << 5) - hash) + char;
    // 32-bit 정수로 바꿉니다.
    hash &= hash;
  }
}

좋은 예

function hashIt(data) {
  let hash = 0;
  const length = data.length;

  for (let i = 0; i < length; i++) {
    const char = data.charCodeAt(i);
    hash = ((hash << 5) - hash) + char;

    // 32-bit 정수로 바꿉니다.
    hash &= hash;
  }
}

주석으로 된 코드를 남기지 않아야한다

나쁜 예

doStuff();
// doOtherStuff();
// doSomeMoreStuff();
// doSoMuchStuff();

좋은 예

doStuff();

코드 기록을 주석으로 남기지 않아야한다

코드 기록은 이미 commit message가 담긴 git log에 나와있을텐데 굳이 주석으로 남길 필요가 없다.

나쁜 예

/**
 * 2016-12-20: 모나드 제거했음, 이해는 되지 않음 (RM)
 * 2016-10-01: 모나드 쓰는 로직 개선 (JP)
 * 2016-02-03: 타입체킹 하는부분 제거 (LI)
 * 2015-03-14: 버그 수정 (JR)
 */
function combine(a, b) {
  return a + b;
}

좋은 예

function combine(a, b) {
  return a + b;
}

코드의 위치를 설명하지 않아야한다

나쁜 예

////////////////////////////////////////////////////////////
// 스코프 모델 정의
////////////////////////////////////////////////////////////
$scope.model = {
  menu: 'foo',
  nav: 'bar'
};

////////////////////////////////////////////////////////////
// actions 설정
////////////////////////////////////////////////////////////
const actions = function() {
  // ...
};

좋은 예

$scope.model = {
  menu: 'foo',
  nav: 'bar'
};

const actions = function() {
  // ...
};

주석에 관한 규칙

Clean Code 책에서의 주석에 관련한 규칙을 정리한 것을 보도록 하자.

1. Always try to explain yourself in code.
2. Don't be redundant.
3. Don't add obvious noise.
4. Don't use closing brace comments.
5. Don't comment out code. Just remove.
6. Use as explanation of intent.
7. Use as clarification of code.
8. Use as warning of consequences.