TSDoc과 Todo Tree 사용해서 효과적으로 주석 작성하기

2024.01.21

코드 문서화의 중요성

"주석이 필요 없는 코드가 좋은 코드다"라는 말은 자주 인용되는 프로그래밍 격언 중 하나입니다. 하지만 실무 경험을 통해 깨달은 것은, 이는 "불필요한 주석을 작성하지 말라"는 의미로 해석되어야 한다는 점입니다. 잘 작성된 주석을 통해 코드의 의도와 제약사항을 명확히 전달할 수 있고 효과적으로 코드를 문서화할 수 있습니다.

효과적인 코드 문서화는 다음과 같은 이점을 제공합니다:

유지보수성 향상: 복잡한 비즈니스 로직의 의도를 명확히 전달
온보딩 시간 단축: 새로운 팀원이 코드베이스를 빠르게 이해
버그 예방: 코드의 제약사항과 주의사항을 명시
API 사용성 개선: 함수와 타입의 사용 방법을 명확히 문서화

이 글에서는 효과적인 코드 문서화를 위한 두 가지 핵심 도구 TSDoc과 Todo Tree를 소개합니다.

이러한 도구들을 활용하면 주석 작성과 관리를 더욱 체계적이고 효율적으로 할 수 있습니다.

TSDoc

TSDoc은 Microsoft에서 개발한 TypeScript 코드 문서화를 위한 공식 표준입니다. JSDoc의 확장 버전으로, TypeScript의 타입 시스템과 완벽하게 통합되어 작동합니다. 주요 특징은 다음과 같습니다:

타입 인식: TypeScript의 타입 정보를 자동으로 인식하고 문서화
IDE 통합: Visual Studio Code 등 주요 IDE에서 자동 완성 및 문서 미리보기 지원
표준화된 태그: @param, @returns, @example 등 표준화된 문서화 태그 제공
마크다운 지원: 문서 내에서 마크다운 문법 사용 가능

아래는 TSDoc을 사용한 문서화 예시입니다.

1. 함수 문서화

아래와 같이 TSDoc에서 제공하는 태그를 사용해서 함수를 문서화 할 수 있습니다.

/**
 * 두 숫자의 가중 평균을 계산합니다.
 *
 * @description
 * 가중치가 지정되지 않은 경우 산술 평균을 계산합니다.
 * 음수 가중치는 0으로 처리됩니다.
 *
 * @param x - 첫 번째 숫자
 * @param y - 두 번째 숫자
 * @param weight - x에 대한 가중치 (0~1)
 * @returns 계산된 가중 평균
 *
 * @example
 * ```typescript
 * // 산술 평균
 * getWeightedAverage(2, 3) // 2.5
 *
 * // 가중 평균
 * getWeightedAverage(2, 3, 0.7) // 2.3
 * ```
 */
function getWeightedAverage(
  x: number,
  y: number,
  weight: number = 0.5
): number {
  const normalizedWeight = Math.max(0, Math.min(1, weight));
  return x * normalizedWeight + y * (1 - normalizedWeight);
}

해당 주석을 통해 함수의 기능, 파라미터, 반환값, 예시 등을 명확히 파악할 수 있습니다.

2. 타입 문서화

아래는 타입을 문서화한 예시입니다.

/**
 * ## 상품 정보
 *
 * @description
 * 커머스 시스템에서 사용되는 상품의 기본 정보를 정의합니다.
 * 모든 금액은 원화(KRW) 기준입니다.
 *
 * @example
 * ```typescript
 * const product: Product = {
 *   id: 1,
 *   name: "샘플 상품",
 *   price: 15000,
 *   status: "ACTIVE"
 * };
 * ```
 */
export type Product = {
  /** 상품 고유 식별자 */
  id: number;
 
  /**
   * 상품명
   * @remarks 최대 100자
   */
  name: string;
 
  /**
   * 판매가격
   * @minimum 100
   * @maximum 10000000
   */
  price: number;
 
  /**
   * 상품 상태
   * @default "DRAFT"
   */
  status: "DRAFT" | "ACTIVE" | "SOLD_OUT" | "DISCONTINUED";
};

이렇게 주석을 추가하면 타입을 사용하는 곳에서 hover 시 @description과 @example 주석을 확인할 수 있습니다. 또한 타입의 각 property에 대해서도 주석이 작성되어 있는데, Product.id와 같이 타입의 각 property에 대해서 접근할 때 주석을 확인할 수 있습니다.

Todo Tree

Todo Tree는 Visual Studio Code의 확장 프로그램으로, 코드베이스 전체의 주석 기반 작업 항목을 체계적으로 관리할 수 있게 해주는 도구입니다. 주요 기능은 다음과 같습니다:

작업 항목 추적: TODO, FIXME 등의 주석 태그를 자동으로 추적
시각적 구성: 사이드바에서 모든 작업 항목을 트리 구조로 표시
커스텀 태그: 프로젝트에 맞는 사용자 정의 태그 설정 가능
필터링: 파일 유형, 태그 유형별 필터링 지원
색상 코딩: 태그별 다른 색상과 아이콘 지정 가능

Todo Tree를 사용하기 위해서는 우선 확장 프로그램을 설치해야 합니다.

설치 후 확장 프로그램을 실행하면 사이드바에 Todo Tree 탭이 추가됩니다. 그리고 vscode/settings.json에 아래와 같은 설정을 추가해서 주석 태그를 추가할 수 있습니다.

// 주석 태그를 추가할 수 있습니다
"todo-tree.general.tags": [
  "TODO",    // 구현 필요
  "FIXME",   // 버그 수정 필요
  "HACK",    // 임시 해결책
  "NOTE",    // 중요 정보
  "PERF",    // 성능 개선 필요
  "SECURITY" // 보안 검토 필요
],
// 태그별 색상, 아이콘 등을 지정할 수 있습니다
"todo-tree.highlights.customHighlight": {
  "TODO": {
    "background": "#54BC52",
    "foreground": "#ffffff",
    "icon": "check",
    "iconColour": "#54BC52",
    "gutterIcon": true
  },
  "FIXME": {
    "background": "#F44336",
    "foreground": "#ffffff",
    "icon": "bug",
    "iconColour": "#F44336"
  },
  "SECURITY": {
    "background": "#FF9800",
    "foreground": "#000000",
    "icon": "shield",
    "iconColour": "#FF9800"
  }
}

마치며

개인적으로는 TSDoc과 Todo Tree 같은 도구를 활용해 주석을 작성하면서 큰 도움을 받았습니다. 특히 복잡한 변수를 다루거나, 다른 팀원이 만든 유틸 함수나 유틸 타입을 사용할 때, 주석이 잘 작성된 코드라면 사용 방법을 훨씬 더 빠르게 이해할 수 있었습니다.

주석은 생산성을 높이는 데 효과적이지만, 주석에 의존하지 않으면 이해할 수 없는 코드를 작성하는 것은 매우 나쁜 습관입니다. 따라서 주석 없이도 충분히 이해할 수 있는 코드를 작성하고 있는지 항상 경계하면서 개발하는 태도가 중요하다고 생각합니다.