코드 품질 - 주석 작성법

한 줄짜리 주석: //

여러 줄: /* ... */

주석은 어떻게 코드가 동작하는지, 왜 동작하는지를 설명하는 데 쓰임.

 

좋지 않은 주석

// 이 코드는 (...)과 (...)을 수행합니다.
// A 개발자가 이 기능에 대해 알고 있으며...

좋은 코드엔 설명이 담긴 주석이 많으면 안된다. 

 

좋은 주석

왜 이런 방법으로 문제를 해결했는지를 설명하는 주석. 이 주석이 없으면,

1. 시간이 꽤 흐른 뒤 코드를 열어본 후 그 코드가 가장 좋은 방식이 아니란 걸 알게 된다.

2. 이전보단 더 명확하고 올바른 방법으로 코드를 개선한다.

3. 리팩토링 과정에서 더 명확하다고 생각했던 방법을 적용하면 문제가 발생한다는 걸 알아낸다. 이미 시도해봤던 방법이기 때문에 왜 이 방법이 먹히지 않는지 희미하게 기억이 떠오른다.

 

함수 용례와 매개변수 정보를 담고 있는 주석

/**
 * x를 n번 곱한 수를 반환함
 *
 * @param {number} x 거듭제곱할 숫자
 * @param {number} n 곱할 횟수, 반드시 자연수여야 함
 * @return {number} x의 n 거듭제곱을 반환함
 */
function pow(x, n) {
  ...
}