공개된 API 요소에는 항상 문서화 주석을 작성하라
자바는 자바독(Javadoc)이라는 유틸리티가 API 문서를 쉽게 작성하도록 도와준다. API 문서를 쉽게 작성하도록 도와주는 도구로 Swagger도 존재한다. 각 장단점을 파악하고 선택해서 사용하면 된다.
이번 아이템에서는 기본적으로 문서화 주석의 작성 요령을 JavaDoc 기준으로 정리해보려고 한다.
JavaDoc 작성 규칙
- 모든 공개된 클래스, 인터페이스, 메서드, 필드에 문서화 주석을 작성해야 한다.
- 공개된 API는 반드시 문서화해야 한다.
- 해당 요소가 무엇을 하는지, 어떻게 사용하는 지 설명해야 한다.
- @param, @return, @throws 태그를 사용한다.
- 메서드의 매개변수, 반환 값, 예외를 설명하는 태그를 사용한다.
- @param: 각 매개변수의 의미와 사용법을 설명한다.
- @return: 메서드의 반환 값을 설명한다.
- @throws: 메서드가 던질 수 있는 예외와 그 예외가 발생하는 상황을 설명한다.
- 간결하고 명확하게 작성해야 한다.
- 필요한 정보를 빠짐없이 제공해야 하지만 불필요하게 장황한 설명은 피해야 한다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
/*
* 사용자 정보를 나타내는 클래스이다.
* 각 사용자는 고유한 사용자 이름을 가지고 있다.
*/
public class User {
private String username;
/*
* 주어진 사용자 이름으로 사용자를 생성한다.
*
* @param username 생성할 사용자의 이름
* @throws IllegalArgumentException 사용자 명이 null이거나 비어있는 경우
*/
public User(String username) {
if (username == null || username.isEmpty()) {
throw new IllegalArgumentException();
}
this.username = username;
}
/*
* 사용자 이름을 반환한다.
*
* @return 사용자 이름
*/
public String getUsername() {
return username;
}
}
그 외 고려 요소
- 보통 문서화 주석의 첫 번째 문장은 해당 요소의 요약 설명으로 간주된다.
- 요약 설명은 반드시 대상의 기능을 고유하게 기술해야 한다.
- 헷갈리지 않으려면 한 클래스 혹은 한 인터페이스 안에서 요약 설명이 똑같은 멤버가 둘 이상이면 안된다.
- 다중 정의된 메서드는 특히 조심해야 한다. 같은 요약 설명이 어울리지만 문서화 주석에서는 허용하지 않는다.
- 제네릭 타입이나 제네릭 메서드를 문서화할 때는 모든 타입 매개변수에 주석을 달아야 한다.
- ex) K는 맵의 Key 타입, V는 맵의 값 타입
- 열거 타입을 문서화할 때는 상수들에도 주석을 달아야 한다.
- 열거 타입의 상수들이 의미하는 바가 무엇인지 설명한다.
- 애노테이션 타입을 문서화할 때는 멤버들에도 모두 주석을 달아야 한다.
- 클래스 혹은 정적 메서드가 쓰레드 안전하든 그렇지 않든 쓰레드 안전 수준을 반드시 API 설명에 포함해야 한다.
정리
문서화 주석을 통해 API를 편리하게 문서화할 수 있다. 공개 API인 경우에는 빠짐없이 설명을 달아주어야 한다.
표준 규약을 일관되게 지키도록 하자.
단, 문서화 도구는 여러가지가 있으므로 각 장단점을 파악하고 팀에 필요하고 편리한, 그리고 목적에 맞는 문서화 도구를 이용하도록 하자.