좋은 주석 다는법

안좋은 주석의 예

---

이 코드에서 무슨 일이 일어나는지 설명하는 주석

예시

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

이유: 주석에 무슨 동작을 하는지 설명해야한다는 자체가
이 코드를 보았을 때 한눈에 알아보기 힘든 코드라는 것을 설명하는 꼴이다.

단, 설명이 꼭 필요한 주석을 작성하는 게 불가피한 경우도 있다. 알고리즘이 복잡한 코드를 작성하는 경우나 최적화를 위해 코드를 약간 비틀어 작성할 땐 설명을 적어주어야 한다. 이런 경우를 제외하곤 간결하고 코드 자체만으로 설명이 가능하게 코딩해야 한다.

좋은 주석의 예

---

고차원 수준 컴포넌트 개요, 컴포넌트 간 상호작용에 대한 설명, 상황에 따른 제어 흐름 등은 주석에 넣는 게 좋다.

예시

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

왜 이렇게 작성했는지에 대한 주석도 사용하면 좋다.

이유

• 코드를 급하게 작성했거나 그 시점에서 가장 나은 방법이라고 생각해서 작성한 코드 일 경우 시간이 흐른뒤 본인 또는 동료가 코드를 보았을 때 가장 좋은 방식이 아니었음을 깨닫고 수정 할 수 있다.

요약

---

주석에 들어가면 좋은 내용

• 고차원 수준 아키텍처
• 함수 용례
• 당장 봐선 명확해 보이지 않는 해결 방법에 대한 설명

주석에 들어가면 좋지 않은 내용

• '코드가 어떻게 동작하는지’와 '코드가 무엇을 하는지’에 대한 설명
• 코드를 간결하게 짤 수 없는 상황이나 코드 자체만으로도 어떤 일을 하는지 충분히 판단할 수 없는 경우에만 주석.