///
Search

아이템56 : 공개된 API 요소에는 항상 문서화 주석을 작성하라

 자바에서 API 문서화

API 문서는 코드가 변경되면 매번 함께 수정해줘야 한다.
자바에서는 자바독이라는 유틸리티를 활용할 수 있다.

 문서화 주석을 작성하는 규칙

 어느 범위까지 문서화를 해야 할까?

공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야 한다.
직렬화할 수 있는 클래스라면 직렬화 형태에 관해서도 작성해야 한다.
기본 생성자에는 문서화 주석을 달 방법이 없다. 따라서 공개 클래스는 기본 생성자를 사용하지 않아야 한다.
유지보수를 고려한다면 공개되지 않은 곳까지도 문서화 주석을 달아야 한다.
문서가 잘 갖춰지지 않은 API는 쓰기 헷갈리기 때문에 오류의 원인이 될 수 있다.

 어떻게 문서화해야 할까?

메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술해야 한다.
어떻게 동작하는지가 아니라 무엇을 하는지 기술해야 한다. (how가 아닌 what)
메서드를 호출하기 위한 전제조건을 모두 나열해야 한다.
성공적으로 수행한 뒤에 만족해야 하는 사후조건도 나열해야 한다.
부작용도 문서화해야 한다.
부작용은 시스템의 상태에 어떠한 변화를 가져오는 것을 의미한다.
ex) 백그라운드 스레드를 시작시키는 메서드라면 해당 사실을 밝혀야 한다.
클래스를 상속용으로 설계할 때
자기사용 패턴에 대해서도 문서에 남겨 올바로 재정의하는 방법을 알려줘야 한다.
자기사용 패턴이란? 자바 8에 추가된 @implSpec 태그로 문서화한다. 해당 메서드와 하위 클래스 사이의 계약을 설명할 수 있다.

 주의할 점은?

 요약 설명할 때 마침표를 주의하자

요약 설명이 끝나는 판단 기준은 {<마침표> <공백> <다음 문장 시작>} 패턴의 <마침표>까지다.
ex) “안녕하세요. 저는 ~~ 입니다.” → “안녕하세요.”가 요약 설명이 될 수 있다.

 제네릭, 열거 타입, 애너테이션 타입을 주의하자

제네릭 타입이나 제네릭 메서드를 문서화할 때 모든 타입 매개변수에 주석을 달아야 한다.
열거 타입을 문서화할 때는 상수들에도 주석을 달아야 한다.
애너테이션 타입을 문서화할 때는 멤버들에도 모두 주석을 달아야 한다.

 자주 누락되는 설명에 대해 주의하자.

스레드 안정성
스레드 안전하든 그렇지 않든 스레드 안전 수준을 반드시 API 설명에 포함되어야 한다.
직렬화 가능성
직렬화할 수 있다면 직렬화 형태도 API 설명에 포함되어야 한다.

 설명이 복잡한 경우

복잡한 API라면 별도의 설명을 링크로 제공하면 좋다.

 핵심 요약

문서화 주석은 API를 문서화하는 가장 효과적인 방법이다.
공개 API라면 빠짐없이 설명을 달자.
표준 규약을 지키자.