공개된 API 요소에는 항상 문서화 주석을 작성하라
자바독이란?
API 문서화 유틸리티 라고 불리며, 소스코드 파일에서 문서화 주석이라는 특수한 형태로
설명을 추려 API 문서로 변환해 준다고 합니다.
공개된 API 요소에는 항상 문서화 주석을 작성하자.
API를 올바로 문서화하려면 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야 된다는 것입니다.
-
메서드 주석에서는 how가 아닌 what을 기술해야 된다.
-
한클래스 안에 설명이 똑같은 맴버가 둘 이상이면 안된다.
-
제네릭 타입이나 메서드를 문서화 할때 모든 타입 매개변수에 주석을 달아야 된다.
-
열거타입을 문서화 할때 상수에도 주석을 달아야 된다.
-
정적메서드의 쓰레드 안전수준은 안전하던 안하던 다 주석에 명시 해야 된다.
자바독 주석 태그
@param- 매개 변수 설명
- 모든 매개변수에 설명을 달아야 한다고 합니다.
@return- 반환 값 설명
- 반환 타입이 void가 아니면 달아야 한다.
@throws- if로 시작해 해당 예외를 던지는 조건 설명
{@code}-
주석 내에 HTML 요소나 다른 자바독 태그를 무시한다.
-
주석에 여러 줄로 된 코드 예시를 넣으려면 pre 태그로 감싸준다.
정리
-
문서화 주석은 API를 문서화하는 효과적인 방법이라고 한다.
-
공개 API라면 빠짐없이 설명을 달아야 한다.
-
표준 규약을 일관되게 지키자.
-
문서화 주석에 임의의 HTML 태그를 사용할 수 있다.
참고
https://github.com/SeolYoungKim/effective_java_study/tree/main
