---
name: code-commenter
description: 프로그램 소스 코드에 이해하기 쉬운 주석을 추가합니다. 코드 주석 추가, 코드 설명, 문서화 요청 시 활성화됩니다.
allowed-tools: Read, Write, Edit, Glob, Grep
---

# Code Commenter

소스 코드에 초보자도 이해할 수 있는 설명적인 주석을 추가하는 스킬입니다.

## 기능

### 주석 유형
- **파일 헤더**: 파일 목적 및 개요
- **함수/메서드 문서**: 입력, 출력, 동작 설명
- **인라인 주석**: 복잡한 로직 설명
- **TODO/FIXME**: 개선 필요 영역 표시
- **섹션 구분**: 코드 영역 구분

### 지원 언어
- JavaScript/TypeScript (JSDoc)
- Python (docstring)
- Java/Kotlin (JavaDoc)
- PHP (PHPDoc)
- Go
- C/C++
- 기타 언어

### 주석 스타일

#### JavaScript/TypeScript (JSDoc)
```javascript
/**
 * 사용자 인증을 처리하고 JWT 토큰을 반환합니다.
 *
 * @param {string} email - 사용자 이메일 주소
 * @param {string} password - 사용자 비밀번호 (평문)
 * @returns {Promise<{token: string, user: Object}>} 인증 토큰과 사용자 정보
 * @throws {AuthenticationError} 이메일 또는 비밀번호가 잘못된 경우
 *
 * @example
 * const result = await authenticateUser('user@example.com', 'password123');
 * console.log(result.token); // 'eyJhbGc...'
 */
async function authenticateUser(email, password) {
  // 데이터베이스에서 사용자 조회
  const user = await User.findByEmail(email);

  // 비밀번호 해시 비교로 인증 검증
  const isValid = await bcrypt.compare(password, user.passwordHash);

  if (!isValid) {
    throw new AuthenticationError('Invalid credentials');
  }

  // JWT 토큰 생성 (24시간 유효)
  const token = jwt.sign({ userId: user.id }, SECRET_KEY, { expiresIn: '24h' });

  return { token, user };
}
```

#### Python (docstring)
```python
def calculate_tax(income: float, deductions: list[float] = None) -> float:
    """
    소득에 대한 세금을 계산합니다.

    누진세율을 적용하여 과세표준에 따른 세금을 계산합니다.
    공제 항목이 있으면 소득에서 차감한 후 계산합니다.

    Args:
        income: 연간 총 소득 (원)
        deductions: 공제 항목 목록 (선택사항)

    Returns:
        계산된 세금 (원)

    Raises:
        ValueError: 소득이 음수인 경우

    Example:
        >>> calculate_tax(50000000, [5000000, 2000000])
        4320000.0
    """
    # 입력값 검증
    if income < 0:
        raise ValueError("소득은 음수가 될 수 없습니다")

    # 공제 적용
    taxable_income = income - sum(deductions or [])

    # 누진세율 적용 (간소화된 예시)
    if taxable_income <= 12000000:
        return taxable_income * 0.06
    elif taxable_income <= 46000000:
        return 720000 + (taxable_income - 12000000) * 0.15
    else:
        return 5820000 + (taxable_income - 46000000) * 0.24
```

#### Java (JavaDoc)
```java
/**
 * 주문 처리 서비스
 *
 * <p>고객의 주문을 생성, 수정, 취소하는 기능을 제공합니다.
 * 재고 확인 및 결제 처리와 연동됩니다.</p>
 *
 * @author 개발팀
 * @version 1.0
 * @since 2024-01-01
 */
public class OrderService {

    /**
     * 새로운 주문을 생성합니다.
     *
     * <p>장바구니의 상품들을 주문으로 변환하고,
     * 재고를 확인한 후 결제를 진행합니다.</p>
     *
     * @param customerId 고객 ID
     * @param cartItems 장바구니 상품 목록
     * @param paymentMethod 결제 수단
     * @return 생성된 주문 객체
     * @throws InsufficientStockException 재고가 부족한 경우
     * @throws PaymentFailedException 결제가 실패한 경우
     */
    public Order createOrder(Long customerId, List<CartItem> cartItems, PaymentMethod paymentMethod) {
        // 재고 확인
        validateStock(cartItems);

        // 주문 생성
        Order order = new Order(customerId, cartItems);

        // 결제 처리
        processPayment(order, paymentMethod);

        return orderRepository.save(order);
    }
}
```

## 주석 가이드라인

### DO (권장)
- 복잡한 비즈니스 로직 설명
- 알고리즘의 의도 설명
- 비직관적인 결정의 이유 설명
- 외부 의존성 및 부작용 문서화
- 매개변수 제약조건 명시

### DON'T (피해야 할 것)
- 코드를 그대로 반복하는 주석
- 너무 명백한 내용 설명
- 오래된/부정확한 주석 방치
- 주석으로 코드 숨기기
- 과도한 주석으로 가독성 저해

## 사용 예시

```
이 코드에 설명 주석을 추가해줘
함수들에 JSDoc 주석을 작성해줘
초보자도 이해할 수 있게 코드를 문서화해줘
```

## 출처
Original skill from skills.cokac.com
