[TypeScript] 문서에 타입 정보를 쓰지 않기

이 글은 이펙티브 타입스크립트 '아이템 30 문서에 타입 정보를 쓰지 않기'를 정리한 내용입니다.

 

 

“코드와 주석이 맞지 않는다면, 둘 다 잘못된 것이다”

• 타입스크립트의 타입 구문 시스템은 간결하고, 구체적이며, 쉽게 읽을 수 있도록 설계되었다.
• 즉, 함수의 입력과 출력의 타입을 코드로 표현하는 것이 주석보다 더 나은 방법이다.
• 타입 구문은 타입스크립트 컴파일러가 체크해주기 때문에, 절대로 구현체와의 정합성이 어긋나지 않는다.
• 누군가 강제하지 않는 이상 주석은 코드와 동기화되지 않는다.
  • 예를 들어, 함수를 변경했을 때 주석을 갱신하는 것을 강제하지 않는다면 주석을 변경하지 않는 일이 발생할 수 있다.
• 하지만, 타입구문은 타입스크립트 타입 체커가 타입 정보를 동기화하도록 강제한다.

 

결과적으로 주석 대신 타입 정보를 작성한다면 코드가 변경된다 하더라도 정보가 정확히 동기화 된다.

• 실제로 프로젝트에 적용한다면, ageNum이라는 변수명보다, age 라는 변수명을 설정하고 해당 타입을 number로 명시하는 것이 좋다.
  • 하지만, 단위가 있는 숫자는 예외다.
    • time / temperature 등의 경우 timeMs / temperatureC로 작성하는 것이 명확하다.

 

요약

• 주석과 변수명에 타입 정보를 적는 것을 피해야 한다. 타입 선언이 중복되는 것으로 끝나면 다행이지만, 최악의 경우는 타입 정보에 모순이 발생하게 된다.
• 타입이 명확하지 않은 경우는 변수명에 단위 정보를 포함하는 것을 고려하는 것이 좋다.