# Javadoc 예시

## 좋은 예시 1: 반환 계약과 예외 조건이 드러나는 메서드

```java
/**
 * Returns the active user for the given email.
 *
 * @param email normalized user email, never {@code null}
 * @return the matching active user
 * @throws UserNotFoundException if no user exists for the given email
 * @throws InactiveUserException if the user exists but is inactive
 */
public User getActiveUserByEmail(String email) {
    ...
}
```

왜 좋은가:

- 호출자가 믿을 수 있는 계약이 보인다
- null 허용 여부와 실패 조건이 드러난다
- 구현 세부가 아니라 API 의미를 설명한다

## 좋은 예시 2: value object 생성 제약 문서화

```java
/**
 * Value object representing a normalized email address.
 *
 * <p>The value is always lowercase and trimmed.
 */
public record UserEmail(String value) {
    ...
}
```

왜 좋은가:

- 타입의 핵심 invariant를 문서화한다
- typical reader가 놓치기 쉬운 제약을 설명한다

## 좋은 예시 3: override는 문서 상속 활용

```java
@Override
public String getName() {
    return name;
}
```

왜 좋은가:

- 상위 계약이 충분하면 중복 문서를 쓰지 않는다
- 불필요한 복붙 Javadoc을 줄인다

## 좋은 예시 4: package/class 수준에서 구조 설명

```java
/**
 * HTTP request/response contracts and exception translation for the auth API.
 *
 * <p>This package owns controllers, request/response DTOs, and client-facing
 * error handling. It must not depend directly on infrastructure implementations.
 */
package com.project.auth.presentation;
```

왜 좋은가:

- package 책임과 금지사항이 드러난다
- architecture 문서와 연결되는 설명이다

## 나쁜 예시 1: 자명한 getter 설명

```java
/**
 * Returns the user name.
 */
public String getUserName() {
    return userName;
}
```

문제:

- 이름만 읽어도 알 수 있다
- 유지보수 시 stale 될 가능성만 늘어난다

개선:

- 생략하거나
- 정말 추가 계약이 있을 때만 적는다

## 나쁜 예시 2: 구현 설명만 적음

```java
/**
 * Uses ArrayList internally and loops over all elements to find the user.
 */
public User findUser(String email) {
    ...
}
```

문제:

- 구현 세부에 과도하게 묶인다
- 리팩터링 시 쉽게 거짓 문서가 된다

개선:

- 호출 계약, 검색 조건, 실패 조건을 설명한다

## 나쁜 예시 3: 태그만 채우는 문서

```java
/**
 * @param email the email
 * @return the user
 */
public User findUser(String email) {
    ...
}
```

문제:

- 독자에게 새로운 정보가 없다
- 형식만 있고 계약이 없다

개선:

- summary와 제약/의미를 써라
- 아니면 생략하라

## 나쁜 예시 4: stale Javadoc 방치

```java
/**
 * Returns a mutable list of authorities.
 */
public List<String> getAuthorities() {
    return List.copyOf(authorities);
}
```

문제:

- 코드와 문서가 충돌한다
- 거짓 문서가 된다

개선:

```java
/**
 * Returns an unmodifiable snapshot of authorities.
 */
public List<String> getAuthorities() {
    return List.copyOf(authorities);
}
```

또는 Javadoc 삭제 후 더 적절한 형태로 재작성