JavaDoc?

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

양식(태그)

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

실무 특징

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

예시

1. Controller

/**
 * [${화면명/기능명}] ${기능_상세_설명}
 *
 * @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

/**
 * ${비즈니스_로직_명}
 *
 * @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쿼리)

/**
 * ${쿼리_질의_목적}
 *
 * @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

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

5. VO

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