문서화 주석은 API를 문서화 하는 가장 효과적인 방법이므로 공개 API라면 이에대한 설명을 빠짐없이 달아야 합니다.
메서드용 문서화 주석
- 메서드와 클라이언트 사이의 규약을 명료하게 기술합니다.
- 사욕용으로 설꼐된 클래스의 메서드가 아니라면 무엇을 하는지 기술합니다.(how가 아닌 what)
- 메서드 호출 전제조건을 모두 기술합니다.
- 메서드가 성공적으로 수행된 후에 만족해야 하는 사후조건을 모두 기술합니다.
전제조건은 @throws태그로 비검사 예외를 선언하여 암시적으로 기술하며 @param태그를 이용해 조건에 영향을 받는 매개변수도 기술합니다ㅣ.
메서드 계약(contract)
- @param 태그를 달아 메서드 계약을 완벽하게 기술합니다.
- 반환타입이
void가 아니라면@return태그를 답니다. - @return 태그의 설명이 메서드 설명과 같다면 생략합니다.
- 발생가능한 예외는 @throws태그를 답니다.
태그 컨벤션
- 관례상 @param태그와 @return 태그의 설명은 매개변수가 뜻하는 값이나 반환값을 설명하는 명사구를 씁니다. 드물게 산술표현식을 사용하기도 합니다.
- @param, @return, @throws 태그 설명에는 마침표를 붙이지 않습니다.
반응형