13 KiB
13 KiB
개발주석표준 가이드
📋 개요
이 문서는 CMS 프로젝트의 JavaDoc 주석 작성 표준을 정의합니다. 일관된 주석 스타일을 통해 코드의 가독성과 유지보수성을 향상시키는 것을 목표로 합니다.
🎯 주석 작성 원칙
1. 기본 원칙
- 명확성: 코드의 의도와 동작을 명확하게 설명
- 일관성: 프로젝트 전체에서 동일한 스타일 적용
- 완전성: 모든 public 메서드와 클래스에 주석 작성
- 최신성: 코드 변경 시 주석도 함께 업데이트
2. 주석 대상
- 필수: public 클래스, 인터페이스, 메서드
- 권장: protected 메서드, 중요한 필드
- 선택: private 메서드 (복잡한 로직인 경우)
📝 JavaDoc 기본 문법
1. 기본 구조
/**
* 클래스나 메서드의 간단한 설명 (첫 번째 문장)
*
* <p>상세한 설명이 필요한 경우 여기에 작성합니다.</p>
*
* @param paramName 파라미터 설명
* @return 반환값 설명
* @throws ExceptionType 예외 상황 설명
* @since 1.0
* @author 작성자명
* @see 관련클래스#메서드
*/
2. 주요 JavaDoc 태그
| 태그 | 설명 | 사용 위치 |
|---|---|---|
@param |
메서드 파라미터 설명 | 메서드 |
@return |
반환값 설명 | 메서드 |
@throws |
예외 상황 설명 | 메서드 |
@since |
도입 버전 | 클래스, 메서드 |
@author |
작성자 | 클래스 |
@version |
버전 정보 | 클래스 |
@see |
관련 항목 참조 | 모든 곳 |
@apiNote |
API 사용 시 주의사항 | 메서드 |
@implNote |
구현 관련 참고사항 | 메서드 |
🎨 HTML 태그 활용 가이드
1. HTML 태그 사용 이유
JavaDoc은 소스코드 주석을 파싱하여 HTML 형태의 API 문서를 자동 생성합니다. HTML 태그를 사용하면:
- 가독성 향상: 구조화된 문서로 이해하기 쉬움
- 자동 문서화: JavaDoc 도구가 예쁜 HTML 문서 생성
- IDE 지원: 개발 도구에서 리치 텍스트로 표시
- 표준 준수: Oracle JavaDoc 스타일 가이드 준수
2. 자주 사용되는 HTML 태그
텍스트 서식
/**
* <p>단락을 구분할 때 사용합니다.</p>
* <b>중요한 내용</b>을 강조할 때 사용합니다.
* <i>이탤릭체</i>로 표시할 때 사용합니다.
* <code>method()</code>와 같은 코드를 표시할 때 사용합니다.
*/
목록 작성
/**
* <p><b>주요 기능:</b></p>
* <ul>
* <li>첫 번째 기능</li>
* <li>두 번째 기능</li>
* <li>세 번째 기능</li>
* </ul>
*
* <p><b>처리 과정:</b></p>
* <ol>
* <li>첫 번째 단계</li>
* <li>두 번째 단계</li>
* <li>세 번째 단계</li>
* </ol>
*/
코드 블록
/**
* <p>사용 예시:</p>
* <pre>
* AuthController controller = new AuthController();
* LoginRequest request = new LoginRequest("user", "password");
* ResponseEntity<LoginResponse> response = controller.login(request);
* </pre>
*/
테이블
/**
* <p><b>HTTP 상태 코드:</b></p>
* <table>
* <tr><th>상태 코드</th><th>설명</th></tr>
* <tr><td>200</td><td>성공</td></tr>
* <tr><td>400</td><td>잘못된 요청</td></tr>
* <tr><td>401</td><td>인증 실패</td></tr>
* </table>
*/
3. HTML 태그 사용 규칙
- <와 >: 제네릭 타입 표현 시
<T>사용 - 줄바꿈:
<br>태그 사용 (가급적<p>태그 권장) - 링크:
{@link ClassName#methodName}사용 - 인라인 코드:
{@code variableName}또는<code>사용
📋 클래스 주석 표준
1. 클래스 주석 템플릿
/**
* 클래스의 간단한 설명
*
* <p>클래스의 상세한 설명과 목적을 여기에 작성합니다.</p>
*
* <p><b>주요 기능:</b></p>
* <ul>
* <li>기능 1</li>
* <li>기능 2</li>
* <li>기능 3</li>
* </ul>
*
* <p><b>사용 예시:</b></p>
* <pre>
* ClassName instance = new ClassName();
* instance.someMethod();
* </pre>
*
* <p><b>주의사항:</b></p>
* <ul>
* <li>주의사항 1</li>
* <li>주의사항 2</li>
* </ul>
*
* @author 작성자명
* @version 1.0
* @since 2024-01-01
*
* @see 관련클래스1
* @see 관련클래스2
*/
public class ClassName {
// ...
}
2. Controller 클래스 주석 예시
/**
* 사용자 관리 API 컨트롤러
*
* <p>사용자 등록, 조회, 수정, 삭제 기능을 제공하는 REST API 컨트롤러입니다.</p>
*
* <p><b>주요 기능:</b></p>
* <ul>
* <li>사용자 등록 및 인증</li>
* <li>사용자 정보 조회 및 수정</li>
* <li>사용자 권한 관리</li>
* </ul>
*
* <p><b>API 엔드포인트:</b></p>
* <ul>
* <li>POST /api/users - 사용자 등록</li>
* <li>GET /api/users/{id} - 사용자 조회</li>
* <li>PUT /api/users/{id} - 사용자 수정</li>
* <li>DELETE /api/users/{id} - 사용자 삭제</li>
* </ul>
*
* <p><b>보안 고려사항:</b></p>
* <ul>
* <li>모든 엔드포인트는 인증이 필요합니다</li>
* <li>개인정보 처리 시 데이터 마스킹 적용</li>
* <li>입력값 검증 및 XSS 방지</li>
* </ul>
*
* @author cms-team
* @version 1.0
* @since 2024-01-01
*
* @see UserService
* @see UserRepository
* @see UserDTO
*/
@RestController
@RequestMapping("/api/users")
public class UserController {
// ...
}
📋 메서드 주석 표준
1. 메서드 주석 템플릿
/**
* 메서드의 간단한 설명
*
* <p>메서드의 상세한 설명과 동작을 여기에 작성합니다.</p>
*
* <p><b>처리 과정:</b></p>
* <ol>
* <li>첫 번째 단계</li>
* <li>두 번째 단계</li>
* <li>세 번째 단계</li>
* </ol>
*
* <p><b>주의사항:</b></p>
* <ul>
* <li>주의사항 1</li>
* <li>주의사항 2</li>
* </ul>
*
* @param param1 첫 번째 파라미터 설명
* - 추가 설명이 필요한 경우
* @param param2 두 번째 파라미터 설명
*
* @return 반환값 설명
* - 성공 시: 설명
* - 실패 시: 설명
*
* @throws ExceptionType1 예외 상황 1 설명
* @throws ExceptionType2 예외 상황 2 설명
*
* @apiNote API 사용 시 주의사항
*
* @see 관련메서드1
* @see 관련메서드2
*
* @since 1.0
*/
public ReturnType methodName(Type param1, Type param2) {
// ...
}
2. API 메서드 주석 예시
/**
* 사용자 로그인 처리
*
* <p>사용자 ID와 비밀번호를 검증하여 JWT 토큰을 생성합니다.</p>
*
* <p><b>처리 과정:</b></p>
* <ol>
* <li>입력값 검증 (@Valid 어노테이션)</li>
* <li>사용자 인증 정보 확인</li>
* <li>JWT 토큰 생성</li>
* <li>사용자 세션 시작</li>
* <li>로그인 메트릭 업데이트</li>
* </ol>
*
* <p><b>보안 고려사항:</b></p>
* <ul>
* <li>비밀번호는 BCrypt로 암호화된 값과 비교</li>
* <li>로그인 실패 시 상세 정보 노출 방지</li>
* <li>로그인 시도 로그 기록</li>
* </ul>
*
* @param request 로그인 요청 정보
* - username: 사용자 ID (3-50자, 필수)
* - password: 비밀번호 (6-100자, 필수)
*
* @return ResponseEntity<LoginResponse> 로그인 응답 정보
* - 성공 시: 200 OK + JWT 토큰, 사용자 역할, 만료 시간
* - 실패 시: 401 Unauthorized + 에러 메시지
*
* @throws InvalidCredentialsException 인증 정보가 올바르지 않은 경우
* @throws RuntimeException 로그인 처리 중 시스템 오류 발생 시
*
* @apiNote 보안상 이유로 로그인 실패 시 구체적인 실패 사유를 반환하지 않습니다.
*
* @see AuthService#login(LoginRequest)
* @see UserSessionService#startSession(String, String, java.time.Instant)
*
* @since 1.0
*/
@PostMapping("/login")
public ResponseEntity<LoginResponse> login(@Valid @RequestBody LoginRequest request) {
// ...
}
📋 필드 주석 표준
1. 필드 주석 템플릿
/**
* 필드의 간단한 설명
*
* <p>필드의 상세한 설명과 용도를 여기에 작성합니다.</p>
*
* <p><b>주의사항:</b></p>
* <ul>
* <li>주의사항 1</li>
* <li>주의사항 2</li>
* </ul>
*
* @since 1.0
*/
private final ServiceType serviceName;
2. 의존성 주입 필드 예시
/**
* 인증 서비스
*
* <p>사용자 로그인/로그아웃 처리 및 JWT 토큰 관리를 담당합니다.</p>
*
* <p><b>주요 기능:</b></p>
* <ul>
* <li>사용자 인증 정보 검증</li>
* <li>JWT 토큰 생성 및 검증</li>
* <li>로그인/로그아웃 처리</li>
* </ul>
*
* @see AuthService
* @since 1.0
*/
private final AuthService authService;
📋 예외 클래스 주석 표준
/**
* 사용자 인증 실패 예외
*
* <p>로그인 시 사용자 ID 또는 비밀번호가 올바르지 않을 때 발생하는 예외입니다.</p>
*
* <p><b>발생 상황:</b></p>
* <ul>
* <li>존재하지 않는 사용자 ID</li>
* <li>잘못된 비밀번호</li>
* <li>계정 잠금 상태</li>
* </ul>
*
* <p><b>처리 방법:</b></p>
* <ul>
* <li>사용자에게 일반적인 오류 메시지 표시</li>
* <li>보안 로그에 상세 정보 기록</li>
* <li>브루트 포스 공격 방지 로직 실행</li>
* </ul>
*
* @author cms-team
* @version 1.0
* @since 2024-01-01
*
* @see AuthService
* @see SecurityException
*/
public class InvalidCredentialsException extends RuntimeException {
// ...
}
📋 인터페이스 주석 표준
/**
* 사용자 인증 서비스 인터페이스
*
* <p>사용자 로그인, 로그아웃, 토큰 관리 등 인증 관련 기능을 정의합니다.</p>
*
* <p><b>구현 클래스:</b></p>
* <ul>
* <li>{@link AuthServiceImpl} - 기본 구현체</li>
* <li>{@link LdapAuthService} - LDAP 연동 구현체</li>
* </ul>
*
* <p><b>주요 기능:</b></p>
* <ul>
* <li>사용자 인증 및 토큰 생성</li>
* <li>로그아웃 및 토큰 무효화</li>
* <li>토큰 유효성 검증</li>
* </ul>
*
* @author cms-team
* @version 1.0
* @since 2024-01-01
*
* @see AuthServiceImpl
* @see TokenProvider
*/
public interface AuthService {
// ...
}
📋 Enum 주석 표준
/**
* 사용자 역할 열거형
*
* <p>시스템 사용자의 권한 수준을 정의합니다.</p>
*
* <p><b>권한 계층:</b></p>
* <ol>
* <li>{@link #ADMIN} - 최고 관리자 권한</li>
* <li>{@link #MANAGER} - 관리자 권한</li>
* <li>{@link #USER} - 일반 사용자 권한</li>
* </ol>
*
* @author cms-team
* @version 1.0
* @since 2024-01-01
*/
public enum Role {
/**
* 시스템 관리자
*
* <p>모든 시스템 기능에 대한 접근 권한을 가집니다.</p>
*
* <p><b>주요 권한:</b></p>
* <ul>
* <li>사용자 관리</li>
* <li>시스템 설정</li>
* <li>모든 데이터 접근</li>
* </ul>
*/
ADMIN,
/**
* 관리자
*
* <p>제한된 관리 기능에 대한 접근 권한을 가집니다.</p>
*/
MANAGER,
/**
* 일반 사용자
*
* <p>기본적인 시스템 기능에 대한 접근 권한을 가집니다.</p>
*/
USER
}
📋 주석 작성 체크리스트
✅ 클래스 주석 체크리스트
- 클래스의 목적과 역할 명시
- 주요 기능 목록 작성
- 사용 예시 코드 포함
- 주의사항 및 제약사항 명시
- @author, @version, @since 태그 작성
- 관련 클래스 @see 태그 추가
✅ 메서드 주석 체크리스트
- 메서드의 목적과 동작 설명
- 처리 과정 단계별 설명
- 모든 @param 태그 작성
- @return 태그 작성 (void 메서드 제외)
- 가능한 예외 @throws 태그 작성
- 보안 관련 주의사항 명시
- 관련 메서드 @see 태그 추가
✅ HTML 태그 체크리스트
- 목록은
<ul>,<ol>,<li>태그 사용 - 강조는
<b>태그 사용 - 단락 구분은
<p>태그 사용 - 코드는
<code>또는<pre>태그 사용 - 제네릭 타입은
<,>사용
📋 도구 및 설정
1. JavaDoc 생성
# Gradle 프로젝트
./gradlew javadoc
# Maven 프로젝트
mvn javadoc:javadoc
# 직접 실행
javadoc -d docs -cp classpath src/**/*.java
2. IDE 설정
- IntelliJ IDEA: Settings > Editor > Code Style > Java > JavaDoc
- Eclipse: Window > Preferences > Java > Code Style > Code Templates
- VS Code: Java Extension Pack + JavaDoc 플러그인
3. 정적 분석 도구
- Checkstyle: JavaDoc 누락 검사
- SpotBugs: 주석 품질 검사
- SonarQube: 문서화 품질 메트릭
📋 참고 자료
💡 팁: 이 가이드를 팀 내에서 공유하고, 코드 리뷰 시 주석 품질도 함께 검토하세요!