JSDoc으로 더 나은 주석 작성하기, 그리고 개발 관련 도서 추천

코드와 그것을 설명하는 그림들, 주석의 역할은 코드를 설명하는 것입니다. 출처: copilot

라이브러리를 사용하다 보면 함수를 작성할 때 해당 함수의 설명이 작성된 경우를 볼 수 있습니다. 이런 설명을 보다보면 함수의 사용법을 더 쉽게 파악할 수 있게 됩니다. 이 기능은 JSDoc라는 기능을 이용한 것으로, 자바스크립트 뿐만 아니라 Java(JavaDoc), python(docstring) 등 다양한 언어에서 지원하며 문법도 거의 똑같다고 합니다.

 

JSDoc을 사용하면 함수의 설명 뿐만 아니라 파라미터와 반환 값의 타입에 대한 정보도 지원해 줄 수 있습니다. 파라미터와 반환값의 타입을 컴퓨터도 알게 되니 타입스크립트처럼 자동완성이 각 타입에 맞게 추천됩니다. 일반 주석과 다른 점은 VSCode와 같은 편집기를 이용한다면 해당 함수가 작성된 곳이 아닌 사용되는 곳에서도 내용을 확인할 수 있다는 것입니다. 이때문에 파일을 이리저리 뒤져보지 않고도 훨씬 편한 개발이 가능합니다.

kakao map 라이브러리에 작성된 JSDoc

작성 방법

설명으로 추가하길 원하는 내용을 /\*\* <내용> \*/와 같은 형식으로 작성하면 됩니다.

/**
 * 두 숫자의 합을 계산합니다.
 * @param {number} a - 첫 번째 숫자
 * @param {number} b - 두 번째 숫자
 * @returns {number} 두 숫자의 합
 */
function add(a, b) {
    return a + b;
}

설명 텍스트

위의 예시에서 "두 숫자의 합을 계산합니다."라는 주석은 단순히 해당 함수를 설명하는 설명 텍스트가 됩니다. 설명 텍스트 자체에는 글자 수 제한이 없습니다. 설명을 길게 작성해도 무방하지만, 가독성을 위해 적절한 길이로 줄바꿈을 해주는 것이 좋습니다. @description 태그를 사용하여 JSDocs에 통일감을 줄 수 있으나 선택 사항이며 기능적 차이는 없습니다.

파라미터 태그

각 매개변수의 타입과 설명을 추가할 수 있습니다. @param {타입} 매개변수명 설명와 같이 사용할 수있습니다.위의 예시에서 @param {number} a - 첫 번째 숫자과 @param {number} b - 두 번째 숫자와 같이 작성할 수 있습니다.

반환값 태그

@returns (또는 @return) {타입} 설명를 사용하면 함수의 반환값에 대한 설명을 추가할 수 있습니다. @returns와 @return은 같은 의미를 지니며, 둘 중 어느 것을 사용해도 동일한 결과를 얻을 수 있습니다. 어떤 차이점이나 특별한 기능적 차이는 없습니다.

사용 예제 태그

설명하려는 함수의 예제를 추가할 수 있습니다. 해당 함수를 사용하였을 때 반환값과 넘겨줄 인자에 대한 예시를 추가할 수 있습니다.

/**
 * 두 숫자의 합을 계산합니다.
 * @param {number} a - 첫 번째 숫자
 * @param {number} b - 두 번째 숫자
 * @returns {number} 두 숫자의 합
 * @example
 * // returns 3
 * add(1, 2);
 */
function add(a, b) {
    return a + b;
}

사용자 정의 타입 태그

@typedef 태그를 이용하면 JSDoc에서 사용자 정의 타입을 선언할 수 있습니다. 이렇게 정의된 타입은 다른 JSDoc 주석에서도 참조할 수 있으며, 더 나아가 다른 JavaScript 파일에서도 활용할 수 있습니다. 대다수의 통합 개발 환경(IDE)가 JSDoc을 지원하기 때문에, JSDoc으로 정의된 타입을 손쉽게 불러와 활용할 수 있습니다.

여기서 타입은 코드에서 값이나 객체를 추상적으로 표현하는 개념을 의미합니다. @property 태그를 활용하여 객체의 속성을 세부적으로 정의함으로써 해당 타입을 명확하게 사용할 수 있습니다.

// types.js

/**
 * 사용자의 정보가 담긴 타입
 * @typedef {Object} User
 * @property {string} name - 사용자 이름
 * @property {number} age - 사용자 나이
 * @property {string} [email] - 사용자 이메일 (선택사항)
 */

// user.js

/**
 * 새로운 사용자를 생성합니다.
 * @param {User} user - 사용자 객체
 * @returns {string} 환영 메시지
 */
function createUser(user) {
  return `Welcome, ${user.name}!`;
}

위와 같은 코드에서 User에 마우스를 올려본다면 다음과 같은 내용을 볼 수 있습니다.

deprecated

더 이상 사용되지 않는 함수나 메서드를 표시합니다. 해당 태그가 붙은 함수를 사용하게 되면 함수에 취소선이 그이며 사용자에게 경고를 합니다. 라이브러리를 사용하다보면 예전 버전의 함수를 사용하려고 할 때 쉽게 볼 수 있습니다.

redux-toolkit에서 deprecated 처리된 createStore 함수

/**
 * 두 숫자의 합을 계산합니다. 더 이상 사용되지 않습니다.
 * @deprecated 이 함수는 addNumbers()로 대체되었습니다.
 * @param {number} a - 첫 번째 숫자
 * @param {number} b - 두 번째 숫자
 * @returns {number} 두 숫자의 합
 */
function add(a, b) {
    return a + b;
}

일반적으로 deprecated 태그를 사용할 때 대체할 함수를 만들어 사용할 수 있도록 해야합니다.

예외

@throws (또는 @exception) 태그를 사용하여 함수가 던질 수 있는 에외를 설명합니다. @throws {타입} 설명 형식으로 작성됩니다. 다만 VSCode를 사용할 경우 타입이 일반 설명과 똑같은 형태로 표시되는 문제가 있습니다. GitHub Issue 1, GitHub Issue 2

/**
 * 두 숫자의 나눗셈을 계산합니다.
 * 0으로 나눌 경우 예외를 던집니다.
 * @param {number} a - 첫 번째 숫자
 * @param {number} b - 두 번째 숫자
 * @returns {number} 나눗셈의 결과
 * @throws {Error} 0으로 나눌 경우 예외
 */
function divide(a, b) {
    if (b === 0) {
        throw new Error("Cannot divide by zero");
    }
    return a / b;
}

더 나은 주석은?

이제껏 JSDoc을 살펴보면서 더 구체적인 주석을 작성하는 법을 알아보았습니다. 함수의 이해를 쉽게 도와주는 주석들이 있다면 코드를 작성하기 편하지만 주석 또한 유지보수해야 될 항목에 포함됩니다. 만약 함수의 사용법이 바뀌었지만 JSDoc으로 작성된 주석을 업데이트하지 않으면 해당 함수를 사용하려는 개발자에게 더 큰 혼란만 줄 뿐입니다. 따라서 함수를 수정할 때 작성된 JSDoc을 확인하여 수정해야될 설명이 있는 지 확인하여야 합니다.

도서 추천 - 클린코드

나쁜 주석은 사족일 뿐입니다. 전혀 유용하지 않습니다. 그렇지만 필요한 주석까지 없애는 건 바람직하지 못합니다. 출처: copilot

더 나은 주석과 관련하여 "클린 코드"라는 책은 함수와 변수 이름으로 해당 함수와 변수가 하는 일과 맡은 역할을 표현하라고 조언합니다. 그리고 잘 작성된 이름은 주석을 달 필요가 없게 만들 수 있습니다. 함수가 하는 일을 설명하는 주석이 나쁜 것은 아니지만 그에 대한 설명은 함수와 변수의 이름으로 표현하는 것이 더 좋습니다. 코드를 수정해야 할 때 신경 쓸 내용이 줄어들기 때문입니다. 복잡한 내용 혹은 개발자의 의도, 언듯 보면 중요성을 알기 힘들지만 함수에 중요한 역할을 미치는 변수나 로직 등 함수나 변수의 이름만으로는 표현하기 힘든 내용을 주석으로 보완하는 것이 더 타당성이 있는 주석이 됩니다.

 

반면 함수의 이름을 통해 충분히 표현된 내용이 주석으로 중복된다면 단지 지루한 반복이 될 뿐입니다. 이렇게 주절주절한 주석은 함수를 리팩터할 때 같이 고쳐야될 짐덩어리가 될 가능성이 높습니다. 만약 함수를 수정할 때 같이 수정하지 못하면 틀린 설명이 될 위험성만이 존재합니다. 단지 위치를 표현하기 위한 주석도 나쁜 주석입니다. 대신, 파일을 분리하여 더 짧고 간단한 소스코드로 유지하는 것이 더 낫습니다. 주석은 분명하고 명확하게 작성하여 사용자가 오해하지 않도록 작성하는 것이 중요합니다. 주석이 모호한 설명을 하거나 주석 처리된 소스코드는 사용자를 혼란스럽게 하므로 차라리 없애는 것이 더 좋습니다.