JavaDoc?

자바 소스 코드 내 특정한 규칙으로 주석을 작성
- API 문서(HTML)을 자동으로 생성해주는 도구
- 또는 표준 주석 양식을 뜻함
Java에서 주석에 대한 표준으로 기존 IDE(Intellij, Eclipse)와 연동성이 좋음

양식(태그)

태그	설명	필수여부	작성 가이드
`@author`	작성자	O	실명, 사번(문의 대상 식별)
`@since`	작성일/버전	O	YYYY.MM.DD나 프로젝트의 버전
`@param`	파라미터 설명	O	파라미터 의미, ~~Null 허용 여부~~, 포맷 등
`@return`	반환값 설명	O	반환되는 데이터 의미
`@throws`	예외 발생	X	비즈니스 로직상 발생할 수 있는 주요 Exception
`@see`	참조 링크	X	AS-IS 클래스, 연관된 유틸리티/상수 클래스 연결
`@deprecated`	사용 금지	X	삭제 예정인 경우 표시

@param에서 Null 허용 여부는 @Nullable, @NotNull로도 표현이 가능하다

실무 특징

차세대의 경우 AS-IS를 추적가능한 꼬리표 역할을 하면 좋음
- 이력 추적: 기존 시스템의 어떤 로직, 왜 변경되었는지 근거 남기기
주석으로 추가적인 이해가 가능하여 커뮤니케이션 비용이 절감되는 효과가 있음
기존 프로젝트라면 이미 IDE에 저장된 관련 양식 정보가 있음
- 신규 프로젝트라면 IDE에 간단한 룰을 정하고 가면 좋음
  - @since의 날짜 포맷이라던가 @author에서 실명이 들어가는지 사번이 들어가는지...

예시

1. Controller

java

/**
 * [${화면명/기능명}] ${기능_상세_설명}
 *
 * @author 00010001
 * @param request  ${요청_데이터_설명_및_필수여부}
 * @param bindingResult ${유효성_검증_결과}
 * @return ${응답_데이터_구조_및_화면이동_경로}
 * @throws Exception ${발생_가능한_주요_예외}
 *
 * ----------------------------------------------------
 * Prj AS-IS Reference:
 * - Method: ${OldController.oldMethodName()}
 * - Note: ${파라미터 구조 변경됨}
 * ----------------------------------------------------
 */
@PostMapping("/submit")
public ResponseEntity<?> submit(@RequestBody NewVO request) { ... }

2. Service

java

/**
 * ${비즈니스_로직_명}
 *
 * @author 00010001
 * @param userId ${사용자_ID}
 * @param amount ${계산할_금액}
 * @return ${계산_결과_값}
 * @throws BizException ${잔액_부족_등_비즈니스_예외_조건}
 *
 * ----------------------------------------------------
 * Prj AS-IS Reference:
 * - Method: ${OldService.processLogic()}
 * - Note: ${파라미터 구조 변경됨}
 * ----------------------------------------------------
 */
public ResultVO processLogic(String userId, BigDecimal amount) { ... }

3. DAO / Mapper (DB쿼리)

java

/**
 * ${쿼리_질의_목적}
 *
 * @param paramMap ${검색_조건_Map (startDate, endDate 필수)}
 * @return ${조회된_목록_List}
 *
 * ----------------------------------------------------
 * Prj AS-IS Reference:
 * - Query ID: ${sqlMap_user.xml -> selectUserList}
 * ----------------------------------------------------
 */
List<UserVO> selectUserList(Map<String, Object> paramMap);

4. Provider / Utility

java

/**
 * ${기능}
 *
 * @param rawData ${가공 전 데이터}
 * @return ${가공 후 데이터 (실패 시 null 반환 여부 명시)}
 * @throws ExternalApiException ${연동_타임아웃_등}
 *
 * ----------------------------------------------------
 * Prj AS-IS Reference:
 * - Method: ${OldUtil.convertData()}
 * ----------------------------------------------------
 */
public String sendToLegacy(String rawData) { ... }

5. VO

java

/**
 * 주민번호 마스킹 처리 후 반환
 *
 * @return ${123456-1****** 형태의 문자열}
 * ----------------------------------------------------
 * Prj AS-IS Reference: 신규 추가 (AS-IS에는 화면에서 처리함)
 * ----------------------------------------------------
 */
public String getMaskedSsn() { ... }