협업과 정확성을 위한 주석 JSDoc

안녕하세요 SOPT 36기 WEB 파트 YB 김정은입니다 👋

 

웹 프론트엔드 개발을 시작하면 가장 먼저 접하는 요소 중 하나인 자바스크립트 사용을 도와줄 도구를 하나 소개해보려고 해요!

 

저는 자바스크립트를 처음 배웠을 때 정말 쉽고 편리한 언어라고 생각했어요. 동적 타입 언어이기 때문에 변수에 어떤 타입이 들어가야 하는지 명시적으로 지정하지 않아요. 코드를 보다 쉽게 작성할 수 있었기 때문에 긍정적으로 느꼈습니다 :)

 

하지만 코드량이 많아지고 협업하게 되면서 장점이 단점이 되었어요. 코드를 작성할 당시에는 문제가 없지만 이후 작성한 코드를 다시 보거나 다른 사람이 작성한 코드를 볼 때면 어려움이 있었어요. 변수에 어떤 타입으로 값을 넣어야 하는지 알기 어려운 경우나, 파라미터로 전달한 값이 함수에서 생각한 타입과 불일치하는 문제 등으로 인해 원하는 대로 동작하지 않았어요. 

 

문제를 보완할 방법이 있을지 고민하던 중 JSDoc에 대해 알게 되었습니다!

---

JSDoc

JSDoc은 자바스크립트에 주석을 달 때 사용하는 마크업 언어예요. JSDoc을 사용하여 작성한 자바스크립트 코드에 주석을 생성하면 이 코드가 어떤 기능을 하고 매개변수는 어떤 타입으로 어떻게 사용되는지, 반환 타입은 어떻게 되는지 등 구체적으로 기록이 가능해요. 또, 작성한 JSDoc을 문서화할 수 있어요.

 

이번 주 과제인 투두리스트 만들기에 사용되는 체크박스를 만드는 함수를 작성하고 JSDoc을 사용하여 주석을 추가했어요. JSDoc으로 작성된 주석은 코드에서 hover 하면 이렇게 나타나요.

함수에 대해 작성한 정보를 바로 알 수 있기 때문에 코드를 작성할 때 유용하게 사용할 수 있어요.

 

이렇게 JSDoc을 사용하여 주석을 달아주면 다른 개발자의 코드를 보더라도 어렵지 않게 코드 리딩이 가능해지고, 이전에 작성한 코드를 보게 되어도 헷갈리지 않을 수 있어요.

---

사용법

JSDoc을 어떻게 작성하는 건지 확인해 볼게요.

JSDoc은 /** */ 안에서 사용해야 하고, 주석을 달고 싶은 코드의 위에 작성해야 해요.

/**완료된 투두 리스트 조회 */
showCompleteList() {
  const filtered = this.todoList.filter((todo) => todo.completed);
  this.render(filtered);
}

간단한 설명만 필요하다면 위와 같이 작성할 수 있어요. 작성된 JSDoc은 아래처럼 나타나요

 

조금 더 구체적으로 나타내고자 한다면 태그를 사용할 수 있어요.

@고유태그 {타입} 이름 - 설명

 

정말 다양한 태그 종류가 있고, https://jsdoc.app/에서 확인 가능해요

 

 

태그를 사용해서 좀 더 구체적으로 작성하면 아래처럼 적을 수 있어요.

/**
 * 체크박스를 생성하고 이벤트 리스너를 추가합니다.
 *
 * @param {string} id - 생성할 체크박스의 id
 * @param {Function} e - 체크박스 상태가 변경될 때 실행될 이벤트 핸들러 함수
 * @returns {HTMLInputElement} 생성된 체크박스
 */
export function createCheckbox(id, e) {
  const checkbox = document.createElement("input");
  checkbox.type = "checkbox";
  checkbox.id = id;

  checkbox.addEventListener("change", e);
  return checkbox;
}

 

이렇게 작성된 JSDoc은 아래와 같이 나타나서 더 자세한 내용을 파악할 수 있어요.

 

 

또, 함수를 작성할 때도 도움이 되는데요, 함수를 작성하면서 파라미터의 타입을 확인할 수 있기 때문에 번거로움이 줄어들고 정확한 코드를 작성할 수 있어요.

id 값을 작성하려 하는데 굵은 글씨로 string 타입이라는 걸 확인할 수 있어요

 

 

아래처럼 사용자 정의 타입을 명시할 수도 있어요.

// types.js

/**
 * 중요도 레벨
 * @typedef {1|2|3} priority
 */

/**
 * 투두 요소 타입
 * @typedef {Object} todo
 * @property {number} id - 투두 항목의 고유 id
 * @property {string} title - 투두 항목의 제목
 * @property {boolean} completed - 항목 완료 여부
 * @property {priority} priority - 항목의 중요도 레벨
 */

export const priority = "priority";
export const todo = "todo";

// table.js

import { todo } from "./types.js";

/**
 * 테이블에 <tr> 요소를 생성합니다.
 *
 * @param {todo} todo - todo 요소 정보
 * @returns {HTMLTableRowElement} 테이블의 행 요소
 */
export function createTableRow(todo) {

사용자 정의 타입을 선언한 후, export 해서 사용했어요. 중요도 레벨은 1, 2, 3으로 사용되기 때문에 해당 값을 가진 타입을 정의하고, todo 타입에 가져와서 사용했어요.

 

정의한 타입을 import 해와서 JSDoc에 사용하면 코드를 작성하면서 타입 힌트를 볼 수 있어요. 

 

사용자 정의 타입은 별도 파일을 생성해서 정의하면 관리가 쉽고 재사용성이 좋아져요. 타입을 중복으로 정의하게 되는 실수도 방지할 수 있어요.

 

JSDoc을 써야 하는 이유

1. 타입 명시 가능
2. 코드 가독성 향상
3. 다른 개발자와 쉬운 커뮤니케이션
4. 에러 방지

 

자바스크립트는 편리한 언어지만, 사용하다 보면 타입으로 인해 많은 번거로움이 생기곤 해요. 이러한 어려움을 느끼신 적이 있거나, 협업을 고려한 코드를 작성하고 싶으신 분이 있다면 JSDoc을 사용해 보는 것을 추천드려요 :)

하지만 JSDoc을 사용한다고 해서 타입스크립트처럼 타입을 체크하고 에러를 발생시키는 것은 아니기 때문에 JSDoc에 의지하지 말고 신경 쓰며 코드를 작성해주어야 해요!

 

 

 

 

읽어주셔서 감사합니다 💙

 

 

ref:

https://jsdoc.app/

https://insight.infograb.net/blog/2024/11/06/js-doc/