자바스크립트(JavaScript) 함수 주석의 표준, JSDoc 활용법

JavaScript에는 함수 주석을 위한 표준 문서화 방식이 있나요?

네, 자바스크립트(JavaScript)에서는 함수 주석을 작성할 때 널리 통용되는 사실상의 표준 방식인 JSDoc 스타일 문서화를 사용합니다. JSDoc은 특별한 문법을 강제하는 공식 언어 사양은 아니지만, 대부분의 개발 도구와 에디터가 이를 지원하기 때문에 업계 표준처럼 활용되고 있습니다.

JSDoc 주석 작성 예시

함수에 대한 설명, 매개변수, 반환값 등을 다음과 같이 /** ... */ 형식으로 주석 처리할 수 있습니다.

/**
 * 두 숫자를 더합니다
 * @param {Number} a - 첫 번째 숫자
 * @param {Number} b - 두 번째 숫자
 * @return {Number} 합계
 */

function sum(a, b) {
    return a + b;
}

JSDoc 태그 설명

• @param {타입} 이름: 함수가 받는 매개변수의 자료형과 설명을 지정합니다.
• @return {타입} 또는 @returns: 함수가 반환하는 값의 자료형과 의미를 명시합니다.
• 주석 첫 줄에는 함수의 역할을 간결하게 요약하여 적습니다.

JSDoc을 사용하면 좋은 점

JSDoc 스타일로 주석을 작성하면 VS Code와 같은 코드 편집기에서 함수 위에 마우스를 올렸을 때 자동완성 힌트와 함께 매개변수 정보를 확인할 수 있습니다. 또한 JSDoc 전용 도구를 사용하면 소스코드에서 바로 HTML 형식의 API 문서를 자동 생성할 수 있어, 팀 단위 프로젝트에서 코드 유지보수성과 가독성을 크게 높여줍니다.