반응형
기본 주석 (JavaScript 초기부터 존재):
- 한 줄 주석: // 를 사용합니다.
- 예시:
// 이것은 한 줄 주석입니다
console.log("Hello, World!");- 여러 줄 주석: 여러 줄에 걸친 설명이 필요할 때 사용됩니다.
- 예시:
/* 이것은
여러 줄
주석입니다 */
console.log("Hello, World!");
JSDoc 주석:
- 사용 목적: 코드의 문서화, 함수의 매개변수와 반환 값 설명, 복잡한 로직의 설명 등에 사용됩니다.
- 기능: IDE에서의 자동 완성, 코드 가독성 향상, 문서 자동 생성 등을 지원합니다.
- 예시:
/**
* 두 숫자의 합을 계산합니다.
* @param {number} a 첫 번째 숫자
* @param {number} b 두 번째 숫자
* @returns {number} 두 숫자의 합
*/
function add(a, b) {
return a + b;
}
TODO/FIXME 주석:
- TODO: 앞으로 해야 할 작업이나 추가해야 할 기능을 표시합니다.
- 예시:
// TODO: 여기에 새로운 기능 구현 필요
- FIXME: 수정이 필요한 코드의 부분을 표시합니다.
- 예시
// FIXME: 이 함수에서 발생하는 버그 수정 필요
JSDoc
JSDoc은 자바스크립트에서 사용되는 강력한 문서화 도구로, 코드의 설명, 함수의 매개변수, 반환 값, 예외 처리 등을 기록하는 데 사용됩니다. JSDoc의 추가적인 기능과 사용법은 다음과 같습니다:
- 타입 지정: 변수나 함수의 반환 타입을 명시적으로 선언할 수 있습니다.
- 클래스와 메소드 문서화: 객체 지향 프로그래밍에서 클래스와 메소드를 문서화하는 데 유용합니다.
- 태그 사용: @param, @returns, @throws, @deprecated 등 다양한 태그를 사용하여 코드에 대한 상세한 정보를 제공합니다.
- 링크 및 예제 추가: 코드의 사용 예제나 관련 문서 링크를 포함할 수 있습니다.
- 문서 자동 생성: JSDoc 주석을 기반으로 HTML 형식의 문서를 자동으로 생성할 수 있습니다.
이러한 기능들을 통해 JSDoc은 코드의 가독성을 높이고, 다른 개발자들이 코드의 동작을 더 쉽게 이해하고 사용할 수 있도록 도와줍니다.
타입 지정:
- 설명: 함수의 매개변수와 반환 값에 타입을 지정합니다.
- 예시:
/**
* 두 숫자의 합을 계산합니다.
* @param {number} a - 첫 번째 숫자
* @param {number} b - 두 번째 숫자
* @returns {number} 두 숫자의 합
*/
function add(a, b) {
return a + b;
}
클래스와 메소드 문서화:
- 설명: 클래스와 그 메소드에 대한 정보를 문서화합니다.
- 예시:
/**
* 사각형을 나타내는 클래스
*/
class Rectangle {
/**
* 사각형을 생성합니다.
* @param {number} width - 폭
* @param {number} height - 높이
*/
constructor(width, height) {
this.width = width;
this.height = height;
}
/**
* 사각형의 면적을 계산합니다.
* @returns {number} 면적
*/
area() {
return this.width * this.height;
}
}
태그 사용:
- 설명: @param, @returns, @throws, @deprecated 등의 태그로 추가 정보를 제공합니다.
- 예시:
/**
* ID에 해당하는 사용자를 반환합니다.
* @param {number} id - 사용자 ID
* @throws {Error} 사용자가 존재하지 않을 경우
* @returns {User} 사용자 객체
*/
function getUser(id) {
// ...
}/**
* 오래된 함수입니다.
* @deprecated 이 함수는 더 이상 사용되지 않으며, 다음 버전에서 제거될 예정입니다. 대신 newFunction을 사용해주세요.
*/
function oldFunction() {
// ...
}
링크 및 예제 추가:
- 설명: 함수 사용법의 예제나 관련 링크를 추가합니다.
- 예시:
/**
* 두 수를 더합니다.
* @example
* add(5, 3); // 8
* @see {@link http://example.com/more_about_addition}
* @param {number} a - 첫 번째 숫자
* @param {number} b - 두 번째 숫자
* @returns {number} 두 숫자의 합
*/
function add(a, b) {
return a + b;
}
문서 자동 생성:
- 설명: JSDoc 주석을 사용하여 HTML 형식의 문서를 자동 생성합니다.
- 예시: 실제 HTML 문서 생성은 JSDoc 툴을 사용하여 명령줄에서 실행해야 하며, 주석이 포함된 소스 코드 파일을 기반으로 문서가 생성됩니다.
이 예시들은 JSDoc의 주요 기능들을 보여줍니다. JSDoc 주석을 적절히 사용하면 코드의 이해도를 높이고, 다른 개발자들에게 유용한 정보를 제공할 수 있습니다.
반응형