좋은 주석과 JSDoc

01. 주석에는 "왜"를 적어요

코드는 무엇을 하는지를 이미 말하고 있어요. 주석이 그걸 한 번 더 말하면 읽을 양만 늘고, 코드만 고치고 주석은 그대로 두는 순간 서로 다른 말을 하게 돼요. 주석이 가치 있는 건 코드만 봐서는 알 수 없는 것을 적을 때예요.

// 나쁜 예 — 코드를 그대로 읽어 줘요
let count = 0;        // count를 0으로 정해요
count++;              // count에 1을 더해요

// 좋은 예 — 왜 그런지, 무엇을 조심할지
// 결제사 API가 1초에 10번까지만 허용해서 요청 사이를 120ms 띄워요.
const REQUEST_GAP_MS = 120;

// 서버가 금액을 문자열로 보내요(정밀도 보존). 계산 전에 숫자로 바꿔요.
const amount = Number(response.amount);

좋은 주석의 예: 그렇게 할 수밖에 없는 이유, 지켜야 할 제약, 일부러 이상해 보이게 쓴 곳의 설명, 참고한 문서 · 이슈 링크, 나중에 할 일(TODO와 이슈 번호).

02. 주석 대신 이름으로

"이 숫자는 뭐지?", "이 조건은 무슨 뜻이지?"를 설명하는 주석은 대부분 이름으로 바꿀 수 있어요. 이름은 코드와 함께 바뀌니 거짓말이 될 일도 적어요.

// 주석으로 설명한 코드
function canBuy1(user) {
  // 19세 이상이고, 휴면 계정이 아니어야 해요
  return user.age >= 19 && user.lastLoginDays < 365;
}

// 이름으로 설명한 코드
const ADULT_AGE = 19;
const DORMANT_AFTER_DAYS = 365;

function canBuy2(user) {
  const isAdult = user.age >= ADULT_AGE;
  const isActive = user.lastLoginDays < DORMANT_AFTER_DAYS;
  return isAdult && isActive;
}

const user = { age: 20, lastLoginDays: 400 };
console.log(canBuy1(user), canBuy2(user)); // false false

두 함수는 똑같이 동작하지만, 아래쪽은 숫자의 뜻과 조건의 의미가 이름에 담겨 있어서 주석이 필요 없어요. 숫자가 바뀌어도 한 곳만 고치면 돼요.

03. JSDoc: 함수 사용 설명서

함수를 쓰는 사람을 위한 설명은 /** … */ 형식의 JSDoc으로 함수 바로 위에 적어요. 무엇을 받고(@param), 무엇을 돌려주는지(@returns)를 종류와 함께 적으면, 편집기가 이 정보를 읽어서 함수를 부를 때 설명 상자로 보여 줘요.

/**
 * 할인을 적용한 가격을 계산해요.
 * @param {number} price 원래 가격 (원)
 * @param {number} [rate=0.1] 할인율 (0~1). 생략하면 10%
 * @returns {number} 할인된 가격 (원)
 */
function discounted(price, rate = 0.1) {
  return price - price * rate;
}

VS Code에서는 파일 맨 위에 // @ts-check를 적으면, 이 JSDoc의 종류 정보로 타입 검사까지 해 줘요. TypeScript로 바꾸지 않아도, 숫자 자리에 문자열을 넣는 실수에 실행 전에 빨간 밑줄이 그어져요.

// @ts-check

discounted('12000');
// 편집기 밑줄: Argument of type 'string' is not assignable to parameter of type 'number'.

모든 함수에 JSDoc을 달 필요는 없어요. 여러 곳에서 쓰는 함수, 다른 사람이 가져다 쓰는 함수(라이브러리 · 공용 유틸), 인자가 헷갈리기 쉬운 함수부터 달아요.

// 배열을 돌아요
for (const p of list) {
  // p의 s가 3이면 건너뛰어요
  if (p.s === 3) continue;
  // 품절 상품은 추천에서 빼요 — 재입고 알림 신청 화면으로 따로 보여 주기 때문이에요
  recommend(p);
}

const SOLD_OUT = 3;

for (const product of products) {
  // 품절 상품은 추천에서 빼요 — 재입고 알림 신청 화면으로 따로 보여 주기 때문이에요
  if (product.status === SOLD_OUT) continue;
  recommend(product);
}

04. 실전 포인트

• 언제 쓰나요? 이유 · 제약 · 우회한 버그(이슈 링크와 함께)는 주석으로 남겨요. 공용 함수에는 JSDoc을 달아요.
• 대신 쓰는 것: "무엇을 하는지"는 이름과 작은 함수로 드러내요. 타입 실수를 프로젝트 전체에서 막고 싶다면 // @ts-check에서 한 걸음 더 나아가 TypeScript를 써요. 쓰지 않는 코드는 주석 처리해 두지 말고 지워요. 필요하면 git 기록에서 되살릴 수 있어요.
• 흔한 실수: 코드를 고치고 주석은 그대로 둬서 둘이 다른 말을 하는 것, 이슈 번호 없는 TODO가 몇 년씩 남는 것이에요.