Item 30 문서에 타입 정보를 쓰지 않기

Avoid comments about types

Conflict between comments and code

문서(주석)가 달린 다음 코드가 있다.

/**
 * 전경색(foreground) 문자열을 반환합니다.
 * 0개 또는 1개의 매개변수를 받습니다.
 * 매개변수가 없을 때는 표준 전경색을 반환합니다.
 * 매개변수가 있을 때는 특정 페이지의 전경색을 반환합니다.
 */
function getForegroundColor(page?: string) {
  return page === 'login' ? { r: 127, g: 127, b: 127 } : { r: 0, g: 0, b: 0 }
}

그런데 코드와 주석의 정보가 맞지 않다는 것을 알 수 있다.

• 함수가 string 형태의 색깔을 반환한다고 적혀 있지만 실제로는 { r, g, b } 객체를 반환한다.

• 주석에는 함수가 0개 또는 1개의 매개변수를 받는다고 설명하고 있지만, 타입 시그니처만 보아도 그냥 알 수 있는 정보이다. (주석을 달 필요조차 없다.)

• 불필요하게 장황하다. 함수 선언, 구현체보다 주석이 더 길다.

누군가가 강제하지 않는 이상 주석은 코드와 동기화되지 않는다. 아마도 코드를 변경한 사람이 주석 갱신하는 것을 깜빡한 것으로 보인다.

따라서 코드는 다음과 같이 고쳐져야 한다.

/** 애플리케이션 또는 특정 페이지의 전경색을 가져옵니다. */
function getForegroundColor(page?: string) {
  return page === 'login' ? { r: 127, g: 127, b: 127 } : { r: 0, g: 0, b: 0 }
}

특정 매개변수를 설명하고 싶다면 JSDoc의 @param 구문을 사용하면 된다. (Item 48)

Just use readonly if the values aren't gonna be changed

값을 변경하지 않는다고 설명하는 주석도 좋지 않다. 그냥 readonly를 달아주면 된다.

// BAD
/** nums를 변경하지 않습니다. */
function sort(nums: number[]) { /* ... */ }

// GOOD
function sort(nums: readonly number[]) { /* ... */ }

But add units if necessary

주석에 적용한 규칙은 변수명에도 그대로 적용할 수 있다. 변수명에는 타입 정보를 넣지 않도록 하자. 변수명을 ageNum으로 하기보다는 age로 하고, 타입을 number로 지정하는 것이 좋다.

• ageNum -> age: number

• personList -> persons: Person[]

• ...

단, 단위가 있는 숫자들은 예외다. 필요하다면 변수명 또는 속성 이름에 단위를 포함하자.

• timeMs는 time보다 명확하다.

• temperatureC는 temparature보다 명확하다.

Item 37에서는 안전한 타입으로 단위를 모델링할 수 있는 '상표'를 설명한다.

Summary

• 주석과 변수명에 타입 정보를 적는 것은 피하자.

  • 타입 선언이 중복되는 것으로 끝나면 다행이다.

  • 최악의 경우 주석과 코드의 타입 정보에 모순이 발생한다.

• 타입이 명확하지 않다면 변수명에 단위 정보를 포함하는 것을 고려하자.