6. JSDoc과 주석 규약

6.1 본문 안 설명은 //로 적고 의도와 단계를 남깁니다

코드를 옮겨 적은 주석은 막고 읽는 데 필요한 설명은 남깁니다.

함수 본문에서 코드의 의도나 절차 단계를 설명할 때는 블록 주석 대신 //를 씁니다. 도메인 규칙, 예외 방어, 외부 API 제약, 부수효과 순서, 긴 절차의 단계 구분에 사용합니다.

내용은 규칙 6.3, 허용된 예외의 이유는 규칙 6.5가 정합니다.

지역 선언에 코드를 옮겨 적은 주석을 답니다.

const toMatchedProducts = (products: Product[], keyword: string) => {
	// keyword를 소문자로 변환
	const lowerKeyword = keyword.trim().toLowerCase();

	return products.filter((product) => product.name.toLowerCase().includes(lowerKeyword));
};

선언 이름이 이미 드러내는 내용만 적은 주석은 지웁니다.

const toMatchedProducts = (products: Product[], keyword: string) => {
	const lowerKeyword = keyword.trim().toLowerCase();

	return products.filter((product) => product.name.toLowerCase().includes(lowerKeyword));
};

지켜야 할 순서와 제약을 주석 없이 코드에만 둡니다.

const submitProductDraft = async (draft: ProductDraft) => {
	if (!draft.name.trim()) {
		return;
	}

	const uploadedAttachments = await uploadAttachments(draft.attachments);
	const savedProduct = await saveProduct({name: draft.name, attachments: uploadedAttachments});

	await queryClient.invalidateQueries({queryKey: ["products"]});

	return savedProduct;
};

//로 제약과 단계를 적습니다.

const submitProductDraft = async (draft: ProductDraft) => {
	// SDK가 빈 문자열을 거부. trim 후 값이 없으면 호출 안 함
	if (!draft.name.trim()) {
		return;
	}

	// 1. 첨부 먼저 업로드. 본문 저장에 참조 ID 필요
	const uploadedAttachments = await uploadAttachments(draft.attachments);

	// 2. 본문 저장
	const savedProduct = await saveProduct({name: draft.name, attachments: uploadedAttachments});

	// 3. 목록 캐시 무효화는 저장 완료 후. 순서가 바뀌면 옛 목록이 다시 채워짐
	await queryClient.invalidateQueries({queryKey: ["products"]});

	return savedProduct;
};

함께 보기

• 6.3 주석에는 목적과 제약만 짧은 한국어 명사형으로 적습니다
• 6.5 컨벤션 예외에는 확인할 수 있는 이유를 적습니다

6.2 경계가 되는 선언에는 JSDoc 헤더를 붙입니다

구현을 읽기 전에 중요한 경계를 찾고 설명할 수 있습니다.

중요한 선언에는 구현을 읽기 전에 역할과 경계를 알 수 있도록 헤더 문서 주석을 씁니다. 빈 본문이나 영문 라벨만으로는 요구를 충족하지 못하며 실제 한국어 설명이 필요합니다.

주요 선언에 헤더 설명이 없습니다.

export const toSortedUserIds = (userIds: string[]): string[] => {
	return uniq(userIds).toSorted();
};

const responseProductList = useProductList();

여러 줄 블록에 설명만 적습니다.

/**
 * 요청 순서 고정. 선택 목록의 중복 ID 제거 후 오름차순 정렬
 */
export const toSortedUserIds = (userIds: string[]): string[] => {
	return uniq(userIds).toSorted();
};

/**
 * 상품 목록 조회. 로딩과 오류는 이 응답 객체로만 판단
 */
const responseProductList = useProductList();

함께 보기

• 6.3 주석에는 목적과 제약만 짧은 한국어 명사형으로 적습니다
• 6.4 JSDoc은 한 줄로 쓰지 않고 여러 줄 블록으로 씁니다

6.3 주석에는 목적과 제약만 짧은 한국어 명사형으로 적습니다

몇 해 뒤에 코드를 여는 사람도 주석을 한눈에 읽고 고칠 수 있습니다.

주석에는 이름과 시그니처에 없는 목적, 제약, 부수효과만 스펙 문서의 한국어로 적습니다. 적을 정보가 없으면 주석을 지웁니다.

문장

낱말

자주 바꿔 쓰는 낱말입니다.

상자

문서 주석은 제목 한 줄이 기본입니다. 본문이 있으면 빈 줄 뒤에 두 칸 들여쓴 목록 하나로 씁니다. 평문 줄은 쓰지 않습니다.

항목 앞에는 종류를 알리는 태그 셋만 씁니다. 그 밖의 사실은 태그 없이 적습니다.

괄호 꼬리는 출처 전용입니다. 누가 정했는지와 그 날짜를 적습니다((백엔드 답변 10-14), (기획 10-07), (피그마 10-01), (사용자 10-13)). 날짜만 있는 (10-14)는 출처가 아닙니다.

내용과 태그

영문이거나 선언 이름을 옮겨 적기만 합니다.

/**
 * This function sorts product refs and returns the result.
 */
export const toSortedProductRefs = (refs: ProductRef[]): ProductRef[] => {
	return sortBy(uniq(refs), [(ref) => ref.id]);
};

/**
 * 상품을 정렬하는 함수
 */
export const toProductsNewestFirst = (products: Product[]): Product[] => {
	return orderBy(products, ["updatedAt", "id"], ["desc", "asc"]);
};

/**
 * route-local product tree props
 */
export interface PgProductTreeSectionProps {
	categoryNodes: ProductCategoryNode[];
}

이름에 없는 정보를 스펙 낱말로 더합니다.

/**
 * 검토 목록 순서 고정. 중복 참조 제거 후 식별자순 정렬
 */
export const toSortedProductRefs = (refs: ProductRef[]): ProductRef[] => {
	return sortBy(uniq(refs), [(ref) => ref.id]);
};

/**
 * 저장 응답 순서 대신 최신순 재정렬
 *
 *   - 제약: 동일 updatedAt 항목 순서는 서버 미보장
 *   - 응답 순서 사용 시 새로고침마다 목록 순서 변동
 */
export const toProductsNewestFirst = (products: Product[]): Product[] => {
	return orderBy(products, ["updatedAt", "id"], ["desc", "asc"]);
};

/**
 * 상품 트리 입력 계약
 */
export interface PgProductTreeSectionProps {
	/**
	 * 사이드바 표시용 분류 노드 목록
	 */
	categoryNodes: ProductCategoryNode[];
}

긴 동사형 문장에 경위, 가운뎃점, 대시, 영어 낱말을 섞습니다.

/**
 * Host 앱/단독 실행/테스트 gallery 가 모두 같은 query client 를 쓰도록 여기 한 곳에서 만들어 둔다 — 예전에는 화면마다 따로 만들어서 retry 횟수가 서로 달랐다.
 */
export const queryClient = new QueryClient({defaultOptions: {queries: {retry: query_retry_count}}});

결론을 제목에 쓰고 조건과 결과는 목록 항목으로 둡니다.

/**
 * 호스트 앱, 단독 실행, 테스트 공용 쿼리 클라이언트
 *
 *   - 재시도 횟수는 이 한 곳에서만 설정
 */
export const queryClient = new QueryClient({defaultOptions: {queries: {retry: query_retry_count}}});

제약 셋을 한 문장에 몰아 씁니다.

/**
 * 상품 저장 요청. 서버가 빈 문자열과 앞뒤 공백을 거부하고, 가격은 원 단위 정수만 받으며, 태그는 한도를 넘기면 저장 자체가 실패하기 때문에 여기서 미리 정리해서 보낸다.
 */
export const toProductSaveRequest = (draft: ProductDraft): ProductSaveRequest => {
	return {
		name: draft.name.trim(),
		price: Math.round(draft.price),
		tags: draft.tags.slice(0, product_tag_limit),
	};
};

요약 한 줄 뒤에 제약을 항목 하나씩 들여쓴 목록으로 나눕니다.

/**
 * 상품 저장 요청. 서버 검증 기준 사전 정리
 *
 *   - 제약: name 앞뒤 공백 불가
 *   - 제약: price 원 단위 정수만 허용
 *   - 제약: tags 한도 초과 시 저장 실패
 */
export const toProductSaveRequest = (draft: ProductDraft): ProductSaveRequest => {
	return {
		name: draft.name.trim(),
		price: Math.round(draft.price),
		tags: draft.tags.slice(0, product_tag_limit),
	};
};

역할 태그로 선언의 성격을 다시 적습니다.

/**
 * @api 상품 목록. 조회 실패는 호출부에서 처리
 */
export const fetchProductList = async (): Promise<Product[]> => {
	return await client.get("/products");
};

태그를 지우고 헤더 첫 줄에 선언이 하는 일을 적습니다.

/**
 * 상품 목록. 조회 실패 처리는 호출부 담당
 */
export const fetchProductList = async (): Promise<Product[]> => {
	return await client.get("/products");
};

바뀐 경위와 날짜만 있는 괄호를 적습니다.

/**
 * 주문 저장 요청
 *
 * 10-07 서버가 수량을 정수로만 받게 되어 반올림 추가
 * 배송 메모는 서버가 200자에서 자름 (10-14)
 */
export const toOrderSaveRequest = (draft: OrderDraft): OrderSaveRequest => {
	return {
		quantity: Math.round(draft.quantity),
		memo: draft.memo.slice(0, order_memo_limit),
	};
};

지금 참인 사실에 출처를 붙이고 없어질 사실은 임시:로 표시합니다.

/**
 * 주문 저장 요청. 서버 검증 기준 사전 정리
 *
 *   - 제약: 수량은 정수만 허용 (백엔드 답변 10-07)
 *   - 임시: 배송 메모 200자 절단, 서버 한도 확장 시 삭제 (기획 10-14)
 */
export const toOrderSaveRequest = (draft: OrderDraft): OrderSaveRequest => {
	return {
		quantity: Math.round(draft.quantity),
		memo: draft.memo.slice(0, order_memo_limit),
	};
};

조회 바인딩 설명이 토막 문장이고 부르는 API가 없습니다.

/**
 * 상품들을 표에 그릴 형태로
 */
const responseProductListSuspense = useGetProductListSuspense(
	{ query: { page: urlParams.page } },
	{ query: { select: (response: ProductListResponseDTO) => toProductRows(response) } },
);

무엇을 조회해 무엇으로 가공하는지와 엔드포인트를 적습니다.

/**
 * 상품 목록 조회, 표 행 뷰모델 가공
 * {@link /api/product}
 */
const responseProductListSuspense = useGetProductListSuspense(
	{page: urlParams.page},
	{ query: { select: (response: ProductListResponseDTO) => toProductRows(response) } },
);

6.4 JSDoc은 한 줄로 쓰지 않고 여러 줄 블록으로 씁니다

선언 위 주석 형태가 파일마다 같아 주석을 검색하고 훑어보기 쉬워집니다.

문서 주석은 /**, *, */를 각각 다른 줄에 둔 여러 줄 블록으로 씁니다.

한 줄 블록과 //로 선언을 설명합니다.

/** 상품 목록. 조회 실패는 호출부에서 처리 */
export const fetchProductList = async (): Promise<Product[]> => {
	return await client.get("/products");
};

// 상품 저장 요청. 응답 본문이 없어 성공은 상태 코드로만 확인
export const saveProduct = async (product: Product): Promise<void> => {
	await client.post("/products", product);
};

같은 내용을 여러 줄 블록으로 고정합니다.

/**
 * 상품 목록. 조회 실패는 호출부에서 처리
 */
export const fetchProductList = async (): Promise<Product[]> => {
	return await client.get("/products");
};

/**
 * 상품 저장 요청. 응답 본문이 없어 성공은 상태 코드로만 확인
 */
export const saveProduct = async (product: Product): Promise<void> => {
	await client.post("/products", product);
};

함께 보기

• 6.2 경계가 되는 선언에는 JSDoc 헤더를 붙입니다

6.5 컨벤션 예외에는 확인할 수 있는 이유를 적습니다

예외가 취향인지 근거가 있는지 코드에서 바로 드러납니다.

확인할 수 있는 근거

규칙이 허용한 예외에는 다른 사람이 확인할 수 있는 근거를 주석으로 남깁니다. “성능을 위해”, “안전하게”, “필요해서”처럼 확인할 수 없는 말은 예외의 근거가 되지 않습니다.

주석 자리

flowchart LR
	q1{"헤더 문서 주석이<br>있는 선언인가?"} -- 아니요 --> q2{"JSX 자식인가?"} -- 아니요 --> r3("해당 줄 바로 위에 //")
	q1 -- 예 --> r1("헤더 블록의 예외: 항목")
	q2 -- 예 --> r2("프레임워크 규칙이<br>정한 형태")

헤더 블록에서는 예외: 태그를 단 목록 항목으로 적습니다. 어투와 상자 꼴은 규칙 6.3를 따릅니다.

확인할 수 없는 말로 예외를 정당화합니다.

// 성능을 위해 메모이제이션
const columns = useMemo(() => {
	return toTableColumns(responseTableColumnsSuspense.data.columns);
}, [responseTableColumnsSuspense.data.columns]);

외부 패키지의 제약을 가리킵니다.

// columns 참조 유지. MUI Data Grid는 참조가 바뀌면 열 너비, 순서를 잃을 수 있음
const columns = useMemo(() => {
	return toTableColumns(responseTableColumnsSuspense.data.columns);
}, [responseTableColumnsSuspense.data.columns]);

막연한 말이라 무엇을 재서 넣었는지 알 수 없습니다.

// 안전하게 다시 계산하지 않도록
const filteredRows = useMemo(() => {
	return rows.filter((row) => matchRow(row, deferredKeyword));
}, [deferredKeyword, rows]);

측정 결과를 가리킵니다.

// 행 5,000개에서 매 렌더 필터링 120ms 측정. 지연한 검색어에만 재계산
const filteredRows = useMemo(() => {
	return rows.filter((row) => matchRow(row, deferredKeyword));
}, [deferredKeyword, rows]);

함께 보기

• 6.3 주석에는 목적과 제약만 짧은 한국어 명사형으로 적습니다