[Effective Java 규칙44] 모든 API 요소에 문서화 주석을 달아라

[Effective Java 규칙44] 모든 API 요소에 문서화 주석을 달아라

Effective Java 2/E 책과 구글링을 통해 내용을 정리하고 개인적인 견해가 포함된 글입니다.

사용할 수 있는 API가 되려면 문서가 있어야 한다. 보통 API 문서를 만들기란 쉽지가 않다. 그러나 Javadoc 이라는 유틸리티를 통해서 API 문서 작업을 쉽게할 수 있다. Javadoc은 문서화 주석( documentation comment )라는 특별한 주석을 통해서 소스 코드로부터 API 문서를 자동으로 생성한다.

좋은 API 문서를 만들려면 API에 포함된 모든 클래스, 인터페이스, 생성자, 메서드, 그리고 필드 선언에 문서화 주석을 달아야 한다. 직렬화 가능 클래스라면 직렬화 형식도 써야한다. 메서드에 대한 문서화 주석은 메서드와 클라이언트 사이의 규약(contract)을 간단명료하게 설명해야 한다. 상속을 위해 설계된 메서드가 아니라면 메서드가 무엇을 하는지를 설명해야지 어떻게 동작하는지 설명하면 안된다.

해당 메서드의 모든 선행조건과 후행조건을 나열하고, 사이드 이펙트(side effect)에 대해서도 문서화 해야한다. 

자바 1.5부터 포함된 제네릭, enum, 어노테이션의 문서화 주석을 만들 때 주의해야될 점이 있다. 제네릭 자료형이나 메서드의 주석을 달때 모든 자료형 인자들을 설명해야 한다. enum 자료형에 주석을 달때는 상수 각각에도 주석을 달아야 한다. 

Javadoc을 안쓴다면 꼭 알아야할 내용은 아니지만 그래도 기억정도는 할 수있게 정리해봤다