모던 JavaScript 튜토리얼을 따라가면서 정리합니다.
3.3. 주석
좋은 코드엔 설명이 담긴(explanatory) 주석이 많아선 안 된다. 주석 없이 코드 자체만으로 코드가 무슨 일을 하는지 쉽게 이해할 수 있어야 한다.
함수 내 코드 일부를 새로운 함수로 옮기고 적절한 이름을 붙이면 함수 이름 자체가 주석 역할을 하므로 코드를 쉽게 이해할 수 잇따. 이런 코드를 자기 설명적인(self-descriptive) 코드라 부른다.
그러나 실무에서는 설명이 담긴 주소를 작성하는 것이 불가피한 경우가 있다.
좋은 주석
아키텍처를 설명하는 주석: 고차원 수준 컴포넌트 개요, 컴포넌트 간 상호작용에 대한 설명, 상황에 따른 제어 흐름은 주석에 넣는 것이 좋다. 이런 주석은 조감도 역할을 해준다.
함수 용례와 매개변수 정보를 담고 있는 주석: JSDoc 이라는 특별한 문법을 사용하면 함수에 관한 문서를 쉽게 작성할 수 있다. 여기엔 함수 용례, 매개변수. 반환값 정보가 들어간다.
1 2 3 4 5 6 7 8 9 10
/** * x를 n번 곱한 수를 반환함 * * @param {number} x 거듭제곱할 숫자 * @param {number} n 곱할 횟수, 반드시 자연수여야 함 * @return {number} x의 n 거듭제곱을 반환함 */ function pow(x, n) { ... }
JSDoc 3 등 툴을 사용하면 주석으로 HTML 문서를 만들 수 있다.
왜 이런 방법으로 문제를 해결했는지 설명하는 주석
다른 개발자 혹은 시간이 흐른 후에 그 코드를 작성한 개발자가 코드를 보고 그때 선택한 방식이 가장 좋은 방식은 아니란 걸 알아낸다. 그리고 이전보다 더 명확하고 올바른 방법이라고 생각하는 방법으로 코드를 개선한다. 리팩토링 과정에서 그 방법을 적용하면 문제가 발생한다는 것을 그제서야 알 수 있다.
미묘한 기능이 있고, 이 기능이 어디에 쓰이는 지 설명하는 주석
요약
주석에 들어가면 좋은 내용
- 고차원 수준의 아키텍처
- 함수 용례
- 당장 봐선 명확해 보이지 않는 해결방법에 대한 설명
주석에 들어가면 좋지 않은 내용
- 코드가 어떻게 동작하는지와 코드가 무엇을 하는지에 대한 설명
- 코드를 간결하게 짤 수 없는 상황이나 코드 자체만으로 어떤 일을 하는지 충분히 판단할 수 없는 경우에만 주석을 넣는다.