주석 리뷰 커맨드
목적
불필요한 주석을 공격적으로 식별하고 제거한다. 코드가 스스로 말해야 한다.
핵심 원칙: 코드에 주석이 필요하면, 그 코드가 잘못된 것이다. 코드를 먼저 고쳐라.
기본 자세: 의심스러우면 제거(REMOVE). 주석은 기술 부채다.
사용자 입력
text
$ARGUMENTS
해석 우선순위:
- •$ARGUMENTS 있음 → 사용자 요청 따르기 (파일 경로,
--all전체 프로젝트 등) - •비어있음 →
git status로 커밋되지 않은 변경사항 확인 - •변경사항 없음 → 최신 커밋 검토
- •전체 프로젝트는 명시적 요청 시에만 (
--all또는 "전체 코드베이스 검토")
주석 원칙
✅ 유일하게 합법적인 주석
이것들이 주석이 허용되는 유일한 경우. 나머지는 모두 제거하거나 리팩토링해야 한다.
| 카테고리 | 엄격한 기준 | 유효한 예시 |
|---|---|---|
| 공개 API 문서화 | 외부 공개 API만. 비공개 코드 = 문서 불필요. | @param userId - 고유 식별자 (내부 헬퍼 함수에는 ❌) |
| 비즈니스 로직 WHY | 도메인 지식이 코드 외부에 있을 때만 | "GDPR 17조에 따라 데이터는 7년간 보존해야 함" |
| 외부 의존성 | 제어 불가능한 서드파티 API 제약 | "Stripe webhook은 지수 백오프로 3회 재시도" (문서 URL 명시) |
| 성능/보안 경고 | 리뷰어를 놀라게 할 반직관적 결정 | "의도적 O(n²) - 도메인 요구사항에 따라 n은 5를 초과하지 않음" |
| 복잡한 패턴 | 패턴 자체가 본질적으로 난해할 때만 (드뭄) | 정규식 분해 - 그러나 먼저 정규식 단순화 시도 |
| 법적/라이선스 | 저작권 헤더, 라이선스 귀속 | "MIT License", "특허 US1234567" (법적 필수) |
| TODO/FIXME | 필수: 담당자, 티켓, 마감일 또는 제거 조건 | // TODO(@username): #1234 Q2 마이그레이션 완료 후 제거 |
분류 기준
❌ REMOVE (즉시 삭제)
기본 가정: 모든 주석은 위의 합법적 사례에 정확히 해당하지 않으면 제거해야 한다.
| 유형 | 예시 | 해결책 |
|---|---|---|
| 코드 흐름 서술 | // 사용자들을 순회 | 삭제 - for (const user of users) 가 명확함 |
| 자명한 설명 | // 카운터 증가 (위에 counter++) | 삭제 |
| 이름 보상 | // 사용자 데이터 가져오기 | getUserData()로 이름 변경, 주석 삭제 |
| WHAT 대신 WHY | // 이메일 형식 검증 | isValidEmailFormat()으로 이름 변경, 삭제 |
| 닫는 괄호 라벨 | } // end if | 삭제 - 올바른 포맷팅이면 명확함 |
| 섹션 구분자 | // ===== Validation ===== | 별도 함수로 추출, 구분자 삭제 |
| 주석 처리된 코드 | // oldFunction() | 삭제 - git log 사용 |
| 오래된/거짓 | 주석이 실제 코드와 모순 | 즉시 삭제 - 이것이 버그를 유발함 |
공격적 규칙: 주석이 코드가 무엇을(WHAT) 하는지 설명하면 (**왜(WHY)**가 아니라), 반드시 제거해야 한다.
⚠️ IMPROVE (리팩토링 필요)
| 유형 | 문제 | 필수 조치 |
|---|---|---|
| 불명확한 TODO | // TODO: 나중에 고치기 | 필수: 담당자, 티켓, 조건 추가 |
| WHAT 설명 | // 사용자 입력 검증 | validateUserInput()으로 이름 변경, 삭제 |
| 장황한 설명 | 여러 단락의 주석 블록 | 문서 파일로 추출, 코드 주석에서 링크 |
| 분산된 비즈니스 로직 | 같은 규칙이 파일들에 중복 | 한 곳에 통합, 이름으로 참조 |
✅ KEEP (합법적으로 필요)
엄격한 기준 - 이것들이 모두 참이어야 함:
- •✅ 위의 합법적 카테고리 중 하나에 해당
- •✅ WHAT이 아닌 WHY 설명
- •✅ 코드만으로 표현 불가
- •✅ 간결함 (이상적으로 한 줄, 최대 3줄)
- •✅ 코드와 동기화됨 (정확성 검증됨)
- •✅ 단일 진실 공급원 (다른 곳에 중복 없음)
워크플로우
1. 분석 대상 결정
bash
git status --porcelain
결정 트리:
- •$ARGUMENTS에 특정 요청 있음 → 요청 따르기
- •$ARGUMENTS 비어있음 + 커밋되지 않은 변경 있음 →
git diff로 변경 파일 분석 - •$ARGUMENTS 비어있음 + 변경 없음 →
git show HEAD로 최신 커밋 분석 - •사용자가 전체 프로젝트 명시적 요청 (
--all) → 전체 프로젝트 스캔
2. 주석 추출
언어별 패턴:
- •TypeScript/JavaScript:
//,/* */,/** */ - •Go:
//,/* */ - •Python:
#,""" """ - •HTML/JSX:
{/* */},<!-- -->
3. 공격적 편향으로 분류
code
각 주석에 대해:
1. 7개 합법적 카테고리 중 하나에 정확히 해당하는가?
아니오 → REMOVE
2. 정보를 더 나은 코드로 표현할 수 있는가?
예 → REMOVE (리팩토링 제안)
3. WHY 대신 WHAT을 설명하는가?
예 → REMOVE
4. 모든 검사 통과?
→ KEEP (그래도 정말 필요한지 검증)
출력 형식
개별 파일 / 변경사항 (직접 조치)
markdown
## 주석 리뷰: {file_path}
### ❌ REMOVE - 즉시 삭제 ({count})
**라인 {n}**: `{comment}`
**이유**: {간단한 근거}
**조치**: 삭제됨
### ⚠️ IMPROVE 또는 제거 ({count})
**라인 {n}**: `{comment}`
**문제**: {이슈}
**옵션**:
1. `{better_code}`로 리팩토링하고 주석 삭제
2. 리팩토링 불가시, 다음으로 개선: `{better_comment}`
**권장**: 옵션 1
### ✅ KEEP ({count})
**라인 {n}**: `{comment}` - 외부 API 제약, 적절히 문서화됨
메타 원칙: 예의보다 코드 품질
당신의 역할: 높은 기준 집행. 직접적이고, 단호하고, 타협 없이.
- •공격적인 것에 사과하지 마라
- •"~일 수도", "~할 수도", "아마도"로 얼버무리지 마라
- •명백한 쓰레기 삭제에 허락 구하지 마라
- •예의 때문에 주석 보존하지 마라
기억하라: 보존하는 모든 주석은 팀이 영원히 유지해야 할 기술 부채다. 무자비하게.