12. 문서화와 주석

12.1 React의 주요 경계 선언에 JSDoc 주석을 붙입니다

공통 문서화 기준에 React 전용 선언을 추가해 누락을 막습니다.

TypeScript 규칙 6.2의 필수 대상에 아래 React 선언을 추가합니다.

주요 경계 선언에 의도 설명이 없습니다.

const handleBackButtonClick: MouseEventHandler<HTMLButtonElement> = (_event) => {
	void navigate("/products");
};

useEffect(() => {
	return subscribeToProductChanges(watchedProductIds);
}, [watchedProductIds]);

선언 의도를 바로 위에 여러 줄 블록으로 적습니다.

/**
 * 저장하지 않고 목록으로 이동. 입력 중인 값은 버림
 */
const handleBackButtonClick: MouseEventHandler<HTMLButtonElement> = (_event) => {
	void navigate("/products");
};

/**
 * 표에 보이는 상품의 변경 알림 구독. 목록이 바뀌면 재구독
 */
useEffect(() => {
	return subscribeToProductChanges(watchedProductIds);
}, [watchedProductIds]);

함께 보기

• TypeScript 6.2 경계가 되는 선언에는 JSDoc 헤더를 붙입니다
• TypeScript 1.4 커스텀 타입과 선언형 형태를 문서화합니다

12.2 JSX 안 주석은 여러 줄 블록으로 씁니다

JSX 주석 형식을 통일해 화면 구역의 역할을 쉽게 읽을 수 있습니다.

JSX 자식 자리의 주석은 {/**, * 내용, */}을 각각 다른 줄에 둔 여러 줄 블록으로 씁니다. 여러 줄로 펼쳐진 형제 블록이 둘 이상이면 블록마다 그 앞에 주석을 짧은 명사형 한 줄로 적습니다. 한 줄 요소와 블록 하나뿐인 반환에는 달지 않습니다.

주석을 한 줄로 접고 마크업 이름을 되풀이합니다.

<div className={clsx("pg_products__root")}>
	{/* 검색 구역 */}
	<PgProductSearchSection />
	{/* PgProductTable */}
	<PgProductTable rows={productRows} />
</div>;

구역이 무엇을 담당하는지 여러 줄 블록으로 적습니다.

<div className={clsx("pg_products__root")}>
	{/**
	 * 검색 구역: 키워드와 카테고리로 목록 질의를 좁히는 이 화면 전용 입력
	 */}
	<PgProductSearchSection />
	<PgProductTable rows={productRows} />
</div>;

예외 이유를 한 줄로 접습니다.

{/* LegacyDatePicker가 className을 받지 않아 배치용 래퍼 필요 */}
<div className={clsx("pg_products__datePicker")}>
	<LegacyDatePicker value={value} onChange={handleChange} />
</div>;

예외 이유도 같은 블록 형태로 적습니다.

{/**
 * LegacyDatePicker가 className을 받지 않아 배치용 래퍼 필요
 */}
<div className={clsx("pg_products__datePicker")}>
	<LegacyDatePicker value={value} onChange={handleChange} />
</div>;

여러 줄 블록 셋 중 하나에만 주석을 둡니다.

<section className={clsx("wg_orderTable__root")}>
	{/**
	 * 헤더 행. 정렬 기준과 단위 표시
	 */}
	<WgOrderTableHeader sort={sort} />
	{rows.map((row) => (
		<WgOrderTableRow key={row.id} row={row} />
	))}
	{expandedRows.map((row) => (
		<WgOrderTableChildRow key={row.id} row={row} />
	))}
</section>;

여러 줄 블록마다 주석을 두어 블록과 함께 접히게 합니다.

<section className={clsx("wg_orderTable__root")}>
	{/**
	 * 헤더 행. 정렬 기준과 단위 표시
	 */}
	<WgOrderTableHeader sort={sort} />
	{/**
	 * 주문 행. 상세 버튼과 아코디언이 있는 기본 행
	 */}
	{rows.map((row) => (
		<WgOrderTableRow key={row.id} row={row} />
	))}
	{/**
	 * 펼친 자식 주문 행. 상세 버튼과 아코디언 없이 같은 칸 구성 반복
	 */}
	{expandedRows.map((row) => (
		<WgOrderTableChildRow key={row.id} row={row} />
	))}
</section>;

함께 보기

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