JSDoc이란?
JSDoc이란, 자바스크립트 소스 코드 파일들에 주석을 달기 위해 사용하는 마크업 언어다. JSDoc을 포함하는 주석에는 작성한 코드의 API를 설명하는 설명 문서를 추가할 수 있다. (참고: 위키백과) JSDoc에 대해서는 이번 프리코스를 하면서 알게 되었다.
지난 미션들에서 코드리뷰를 하면서 간혹 JSDoc을 사용하는 지원자들이 보였다. 아무래도 아직은 다른 사람들의 코드를 보는 게 익숙하지 않아 JSDoc의 도움을 받았기에 나도 사용해 보기로 했다.
사용하기
이번 미션에서 핵심 파일이라고도 할 수 있는 서비스 레이어 (EventProcessor), 컨트롤러 (EventPlanner)에 아래와 같이 사용했다. 함수가 어떤 기능을 하는지, 어떤 매개변수를 전달하는지, 그리고 어떤 타입의 어떤 값이 리턴되는지 설명했다.
/**
* 총 할인되지 않은 금액과 혜택 대상 여부를 기반으로 한 가격 계산
* @param {number} totalAmountBeforeDiscount - 할인되지 않은 총 금액
* @param {boolean} isEligibleForBenefit - 혜택 대상 자격 여부
* @returns {Object} - 가격 정보
*/
#calculatePricing(totalAmountBeforeDiscount, isEligibleForBenefit) {
const pricing = {
totalAmountBeforeDiscount,
totalBenefit: EVENT.zero,
finalPayAmount: totalAmountBeforeDiscount,
};
if (isEligibleForBenefit) {
pricing.totalBenefit = this.#calculateTotalBenefit();
pricing.finalPayAmount = this.#calculateTotalPayAfterDiscount();
}
return pricing;
}
JavaScript
복사
사용 효과
JSDoc을 사용하면 아래와 같이 VSCode에서 자동으로 API문서를 생성해 사용하는 함수에 대한 정보를 보여주므로, 매개변수를 어떻게 부여해야 하는지, 리턴 값의 타입은 어떤지 기억이 안 난다면 코드 위에 마우스 커서를 올리면 된다.
함수에 대한 정보
여러 사람들에게 코드리뷰를 받거나, 협업을 할 때는 앞으로 JSDoc을 사용해야겠다는 생각이 들었다. 물론 작업하는 나에게도 도움이 되기도 하니까.