JavaScript 함수 주석 처리의 표준 방식: JSDoc 활용법

JavaScript에서 함수 주석 처리의 표준은 무엇일까요?

JavaScript에서 함수에 주석을 달 때 업계에서 널리 사용되는 표준은 바로 JSDoc입니다. JSDoc은 /**와 */로 감싸는 문서화 주석(Documentation Comment) 형식으로, 함수의 목적, 매개변수, 반환값 등을 구조적으로 설명할 수 있어 코드 가독성과 유지보수성을 크게 높여줍니다.

특히 VS Code와 같은 대부분의 코드 에디터는 JSDoc 주석을 인식하여 자동 완성 기능과 타입 힌트를 제공하기 때문에, 실무 개발 환경에서 사실상의 표준으로 자리 잡았습니다.

JSDoc 주석 작성 예시

다음은 두 숫자를 더하는 함수에 JSDoc 표준 주석을 적용한 예시입니다.

/**
 * 두 숫자를 더합니다
 * @param {Number} num1 - 첫 번째 숫자
 * @param {Number} num2 - 두 번째 숫자
 * @return {Number} 두 수의 합
 */
function sum(num1, num2) {
    return num1 + num2;
}

주요 JSDoc 태그 정리

• @param: 함수가 받는 매개변수의 이름, 타입, 설명을 명시합니다.
• @return (또는 @returns): 함수가 반환하는 값의 타입과 설명을 나타냅니다.
• @description: 함수의 전체적인 설명을 추가할 때 사용합니다.

참고: 일반 주석과의 차이점

JavaScript에는 한 줄 주석(//)과 여러 줄 주석(/* */)이 있습니다. 하지만 이들은 단순히 코드 실행에서 제외하는 용도로 쓰이는 반면, JSDoc 스타일의 /** */ 주석은 도구가 해석할 수 있는 구조화된 문서라는 점에서 차별화됩니다.

따라서 함수를 주석 처리하거나 문서화할 때는 JSDoc 표준을 따르는 것이 가장 좋은 선택입니다.