39. 주석 작성 목적, 주석 작성 사례

주석 작성의 궁극적인 목적

• 코드가 목적을 달성하기 위한

  • 기능, 시나리오 등을 생각하고 정리하는 것

• 이것을 문법에 맞추어 작성한 것이 코드

• 코드를 작성하기 전에

  • 우선 먼저 정리한 생각을 주석으로 작성
  • 어렵지만 처음 배울 때부터 습관화

• 주석 작성 기준

  • 코드의 목적, 결과가 미치는 영향을 작성
  • 다른 사람이 알 수 있도록 자세하게 작성

주석 사례

/**
* @function calculateAmount
* 1. 파라미터로 받은 수량에 단가를 곱해
*    금액을 계산하고 결과 값을 반환한다.
* 2. 수량과 단가의 0 체크는
*    함수를 호출하기 전에 하므로 체크하지 않는다.
* @param {Number} quantity, 수량
* @param {Number} price, 단가
* @return {Number} 계산 결과
*/
function calculateAmount (quantity, price) {
    // 주석을 자세하게 작성하기 위해
    // 함수 코드를 분리하는 경우도 있습니다.
}

위의 주석 형태는 자바스크립트 문법상으로 정리되어있는 주석은 아니고, 개발자들이 관례적으로 사용하다가 지금은 일반적인 방법이 된 사례입니다.
/** 이 형태로 주석을 작성하면 자동으로 웹 문서를 만들어주는 툴이 있었습니다.
그것에 맞추다보니 일반화가 된 것입니다.
@도 그 툴에서 사용하는 기준이었습니다.

위의 예시처럼 시나리오를 작성합니다.
그리고 처리안한 부분이 있다면 그 이유도 명확하게 작성합니다.
그래야 다른 개발자가 보고 오해를 안합니다.

함수는 알아보기 쉽게 최소화시킵니다.
함수 코드가 너무 길면 함수명이 구체적이지 않게 됩니다.