프론트엔드 개발자를 위한 JSDoc 기반 주석 가이드
왜 주석이 중요한가?
"좋은 코드에는 주석이 필요 없다"는 말이 있지만, 실무에선 그렇지 않다.
나도 주석을 잘 안쓰는 편이긴 한데 이 글 쓰다보니 다시 써야겠음 ㅎㅎ;
주석은 팀원, 미래의 나, 그리고 협업자에게 “이 코드가 왜 존재하는지” 설명하는 가장 강력한 도구
프론트엔드 개발에선 특히,
- UI 흐름
- API 요청
- 사용자 이벤트
- 컴포넌트 상태 변화
등 복잡한 맥락이 얽히기 때문에, 주석이 문서 이상의 역할을 한다.
주석의 조건
| 조건 | 설명 |
|---|---|
| 명확성 | 누가 봐도 쉽게 이해 가능한 설명 |
| 간결성 | 핵심만 간단하게 전달 |
| 일관성 | 팀의 주석 스타일 유지 |
| 문서화 가능성 | 자동 문서화 도구가 읽을 수 있는 형식 사용 |
💡 팁: "무엇"보다 "왜"를 설명하라
JSDoc 기본 문법
JSDoc이란?
JSDoc은 자바스크립트랑 타입스크립트에서 주석으로 코드를 문서화할 수 있게 해주는 도구
그냥 주석을 다는 게 아니라, 정해진 규칙(@param, @returns 등)을 따라 쓰면
자동으로 API 문서도 만들 수 있고, 에디터에서 타입 힌트도 주고, 코드 이해가 더 쉬워진다
/**
* 사용자 이름을 포맷팅합니다.
* @param {string} firstName - 이름
* @param {string} lastName - 성
* @returns {string} "성, 이름" 형식의 포맷된 문자열
*/
function formatUserName(firstName, lastName) {
return `${lastName}, ${firstName}`;
}자주 쓰는 태그
| 태그 | 설명 |
|---|---|
@param | 파라미터 설명 |
@returns | 반환값 설명 |
@example | 사용 예시 |
@typedef | 커스텀 타입 정의 |
@property | 객체 속성 설명 |
@deprecated | 더 이상 사용하지 말아야 할 함수 표시 |
React 컴포넌트에 주석 달기
/**
* 기본 버튼 컴포넌트입니다.
*
* @param {Object} props
* @param {string} props.label - 버튼에 표시될 텍스트
* @param {() => void} props.onClick - 클릭 시 실행될 함수
* @param {boolean} [props.disabled=false] - 비활성화 여부
* @returns {JSX.Element} 렌더링된 버튼 엘리먼트
*/
const Button = ({ label, onClick, disabled = false }) => (
<button onClick={onClick} disabled={disabled}>
{label}
</button>
);실전에서 주석 잘 쓰는 팁
- ❌
// 버튼 클릭 이벤트 처리→ 이건 코드만 봐도 앎 - ❌
// 사용자 데이터를 서버에 전송하는 이벤트→ 이건 여전히 "무엇"을 말하고 있음 - ✅
// 로그인 성공 시 사용자 정보를 저장해 다음 단계로 이동하기 위함→ 왜 필요한지 설명하는 주석 - ✅ 복잡한 조건문이나 API 호출 흐름엔 주석 필수
- ✅ 주석은 리팩토링 대상! 오래된 주석은 잘못된 정보가 될 수 있음
🛠️ 유용한 도구
| 도구 | 설명 |
|---|---|
VS Code + TypeScript | 타입 기반 자동완성 + 주석 힌트 |
JSDoc, Typedoc | 문서 자동 생성 도구 |
eslint-plugin-jsdoc | JSDoc 누락/오류 체크 플러그인 |
Cursor에서 JSDoc 자동 주석 활용하기
AI가 발전하는 상황에서 굳이 내가 주석을 일일히?
요즘 내가 메인으로 사용하는 IDE인 Cursor는 AI 기반 코드 보조 툴이라서, JSDoc 스타일의 주석도 자동으로 달 수 있다.
JSDoc 자동 생성
함수, 컴포넌트 위에 /** 입력 후 Enter를 치면 → Cursor가 함수 시그니처를 읽고 자동으로 JSDoc 블록을 생성해 줌.
예를 들어:
/**
*
*/
function add(a: number, b: number): number {
return a + b;
}위 상태에서 Enter를 누르면 아래처럼 자동 완성:
/**
* 두 숫자를 더합니다.
* @param {number} a - 첫 번째 숫자
* @param {number} b - 두 번째 숫자
* @returns {number} 합계
*/
function add(a: number, b: number): number {
return a + b;
}
Frontend Dev.