[etc] JSDoc를 사용하여 아름답게 주석 남기기

 

1. Typescript 대신 JSDoc을 사용하는 이유?

Type을 정확히 잡아내기 위해선 Typescript를 쓰는 것이 좋지만, Typescript의 너무 엄격한 규정은 개발 초기 변경사항이 많을 때 등 불편한 경우가 많다. 또한, Typescript -> Javascript로의 변환이 너무 불편함 + 코드 양의 증가로 클린코드 작성이 어려운 것이 JSDoc을 추천하는 이유다.

 

2. JSDoc을 사용해야하는 이유

function example(num, str) {
    return num + str;
}

일반적으로 Javascript 내에서 함수를 작성할 때 너무 관대한 Javascript이기에 인수/인자 값의 type이 무엇인지 알 수 없다.

이로인해 type으로 인한 문제 발생 위험이 증가하고, 이는 Typescript가 부흥하게 된 이유에 가장 부합하다.

 

3. JSDoc을 사용하여 주석 남기기

 

// /** */ 를 사용하여 주석을 달면 하단의 변수나 함수에 대한 설명을 남길 수 있다.

/** JSDoc을 사용하여 주석 남기기 */

// /** */ 주석은 한 줄 뿐 아니라 여러 줄로도 표기할 수 있다.

/**
* JSDoc은 이렇게 주석을 여러 줄로 남길 수 있습니다.
*/

// 그 외에도 @를 사용하여 코멘트 태그를 사용할 수 있다. 예시는 하단에 Microsoft가 제공하는 내용 참고.

Create JSDoc Comments for JavaScript IntelliSense - Visual Studio 2015

JSDoc Comment Tags

The following standard JSDoc comment tags are used by IntelliSense to display information about your code.

JSDoc tagSyntaxNotes

@deprecated	@deprecated description	Specifies a deprecated function or method.
@description	@description description	Specifies the description for a function or method.
@param	@param {type} parameterNamedescription	Specifies information for a parameter in a function or method. TypeScript also supports @paramTag.
@property	@property {type} propertyName	Specifies information, including a description, for either a field or member that's defined on an object.
@returns	@returns {type}	Specifies a return value. For TypeScript, use @returnType instead of @returns.
@summary	@summary description	Specifies the description for a function or method (same as @description).
@type	@type {type}	Specifies the type for a constant or a variable.
@typedef	@typedef {type} customTypeName	Specifies a custom type.

---

 

4. 사용예시

 

1) 기본 주석 달기

/**
 * num + str 을 합해 문자로 return하는 함수
 */
function example(num, str) {
    return num + str;
}

 

2) @param 변수 내용으로 각 변수에 필요한 주석 달기 + @returns로 함수가 return하는 주석 달기

/**
 * num + str 을 합해 문자로 return하는 함수
 * @param num 숫자를 넣으세요
 * @param str 문자열을 넣으세요
 * @returns 두 값을 더해 문자로 return함
 */
function example(num, str) {
    return num + str;
}

 

3) 각 변수의 type을 @param {타입} 변수 로 전달하기

/**
 * num + str 을 합해 문자로 return하는 함수
 * @param {number} num 숫자를 넣으세요
 * @param {string} str 문자열을 넣으세요
 * @returns 두 값을 더해 문자로 return함
 */
function example(num, str) {
    return num + str;
}

 

4) Version을 전달하는 @version 태그, 참고 사이트를 전달하는 @see 태그

/**
 * @version 1.3.0
 * @see https://orbit-orbit.tistory.com/
 */
function example(num, str) {
    return num + str;
}

 

5) 읽기 전용이라는 내용을 전달하는 @readonly 태그, 함수의 type을 전달하는 @const 태그

/**
 * @readonly
 * @const {number}
 */
const num = 1;

 

6) 해당 함수의 할 일 목록 전달하는 @todo 태그

/**
 * @todo 내일까지 개발 완료해야 함
 */
function example(num, str) {
    return num + str;
}

 

7) 더 이상 사용하지 않는 함수임을 알리는 @deprecated 태그

/**
 * @deprecated 이제 사용하지 않는 함수입니다.
 */
function example(num, str) {
    return num + str;
}

example()

 

8) 변수의 타입을 전달하는 @type 태그

/** @type {string | number} */
var str = "string";

/** @type {number[]} */
var numArr = [1,2,3];

 

항간에는 Typescript와 JSDoc 모두를 사용한다는 개발자들도 있어보이고, JSDoc만 사용한다는 사람도 있는 것 같고 각자 프로젝트에 맞게 혹은 대세에 맞게 작성하면 될 것 같음!