JSDoc — TypeScript 없이 타입 힌트 얻기

이 토픽을 마치면

JSDoc 주석으로 JavaScript에 타입 정보를 부여하는 방법을 알게 됩니다. TypeScript를 도입하지 않아도 에디터 자동완성과 타입 검사를 받을 수 있다는 걸 이해하게 됩니다.

문제: TypeScript는 좋은데 도입이 무겁습니다

TypeScript를 쓰면 타입 오류를 미리 잡아줍니다. 좋습니다. 그런데 기존 JavaScript 프로젝트에 TypeScript를 도입하려면 tsconfig.json 설정부터 빌드 파이프라인 수정, .js → .ts 파일 확장자 변경까지 해야 합니다. 10만 줄짜리 레거시 프로젝트에 이걸 한번에 적용하는 건 현실적으로 불가능합니다.

JSDoc은 이 문제를 해결합니다. 파일 확장자도 안 바꾸고, 빌드 설정도 안 건드리고, 주석만 달면 됩니다.

JSDoc 기본: 함수에 타입 붙이기

javascript

/**
 * @param {string} name - 사용자 이름
 * @param {number} age - 나이
 * @returns {string} 인사 메시지
 */
function greet(name, age) {
  return `${name}님은 ${age}살입니다.`;
}

이렇게 작성하면 VS Code가 greet를 호출할 때 name은 문자열, age는 숫자를 넣어야 한다고 알려줍니다. 빨간 줄도 나옵니다 — greet(123, "twenty") 하면 경고합니다.

핵심은 이겁니다: .js 파일인데 TypeScript처럼 타입 검사를 받는 겁니다. 주석이니까 런타임에는 완전히 무시됩니다.

객체와 배열에 타입 붙이기

javascript

/**
 * @param {{ id: number, name: string }} user
 * @param {string[]} tags
 * @returns {boolean}
 */
function hasTag(user, tags) {
  return tags.includes(user.name);
}

user는 id와 name이 있는 객체, tags는 문자열 배열이라고 선언한 것입니다. 에디터에서 user. 을 찍으면 id와 name이 자동완성됩니다.

복잡한 객체를 반복해서 쓸 때는 @typedef로 이름을 붙일 수 있습니다:

javascript

/**
 * @typedef {Object} Product
 * @property {number} id
 * @property {string} name
 * @property {number} price
 */

/** @param {Product} item */
function formatPrice(item) {
  return `${item.name}: ${item.price}원`;
}

Product라는 타입을 한 번 정의해 두면 프로젝트 어디서든 @param {Product}로 참조할 수 있습니다.

VS Code에서 바로 써먹기

JS 파일 맨 위에 한 줄을 추가하면 TypeScript의 타입 검사기가 해당 파일을 검사합니다:

javascript

// @ts-check

이게 전부입니다. tsconfig.json 없이도, TypeScript 설치 없이도, VS Code에 내장된 TypeScript 언어 서버가 JSDoc 주석을 읽어서 타입을 검사합니다.

@ts-check를 파일 하나에만 넣을 수도 있고, jsconfig.json에 "checkJs": true를 설정하면 프로젝트 전체에 적용됩니다.

실무에서 쓰이는 방식

점진적 마이그레이션 — TypeScript 전면 도입 전에 JSDoc으로 핵심 파일부터 타입을 잡습니다. 나중에 진짜 TypeScript로 옮기더라도 JSDoc에서 정의한 타입 정보가 이미 있으니 변환이 수월합니다.

라이브러리 배포 — npm 패키지를 JavaScript로 배포하면서 JSDoc으로 타입 정보를 제공하는 프로젝트가 많습니다. Svelte가 대표적인 사례입니다. TypeScript 소스 없이도 사용자가 자동완성을 받을 수 있습니다.

20년차 JavaScript 개발자들의 선택 — TypeScript 문법을 익히기보다 이미 아는 JavaScript에 주석만 추가하는 걸 선호하는 경우가 있습니다. 생산성 차이가 작고, 빌드 단계가 하나 줄어듭니다.

JSDoc의 한계

만능은 아닙니다. 제네릭 타입이나 유니온 타입이 복잡해지면 주석이 코드보다 길어집니다. 조건부 타입(Conditional Types)이나 매핑 타입(Mapped Types) 같은 TypeScript 고급 기능은 JSDoc으로 표현이 안 되거나 매우 불편합니다.

프로젝트가 커지고 팀이 커지면 결국 TypeScript로 가는 게 유지보수에 유리합니다. JSDoc은 **"아직 TypeScript를 못 쓰는 상황에서 최대한 타입 안전성을 확보하는 도구"**라고 생각하면 됩니다.

핵심

JSDoc은 주석만으로 JavaScript에 타입 정보를 부여하는 방식입니다. TypeScript를 도입하지 않아도 에디터 자동완성과 타입 검사를 받을 수 있습니다. 파일 상단에 // @ts-check 한 줄이면 즉시 활성화됩니다.