[Effective Java] 공개된 API 요소에는 항상 문서화 주석을 작성하라

 

💥 개요

API를 작성함에 있어서 잘 작성된 문서는 중요하다. 공식 언어 명세에는 없지만 자바 프로그래머라면 알아야하는 업계 표준 API라 할 수 있다.

자바에서는 이 귀찮은 작업을 자바독이라는 유틸리티가 도와준다.

https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html

How to Write Doc Comments for the Javadoc Tool

API를 올바로 문서화하려면 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야 한다. 공개 API만큼 친절하게 설명하지 않더라도 유지보수를 고려해 대다수에 문서화 주석을 달아야한다. 메소드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술해야 한다.

 

🔎 지켜야할 규칙

• 항상 how가 아닌 what을 기술해야 한다.
• 클라이언트가 해당 메서드를 호출하기 위한 전제조건을 모두 나열해야 한다.
• 메서드가 성공적으로 수행된 후 만족해야 하는 사후조건을 모두 나열해야 한다.
• 일반적으로 전제조건은 @throws 태그로 비검사 예외를 선언하여 암시적으로 기술한다.
• @param 태그를 이용해 그 조건에 영향받는 매개변수에 기술한다.
• 부작용도 문서화해야 한다.(ex.백그라운드 스레드를 시작하는 메서드라면 밝혀야함)
• 완벽히 기술하려면 모든 매개변수에 @param, 반환 타입이 void가 아니라면 @return, 발생 가능성이 있는 모든 예외에 @throws를 달아야 한다.
• 클래스 혹은 정적 메서드가 스레드 안전하든 그렇지 않든, 스레드 안전 수준을 반드시 API 설명에 포함해야 한다.

 

❤️ 효과적인 문서 작성법

문서화 주석은 html 태그를 인식한다. 그렇기 때문에 편리하지만, HTML 메타 문자인 < 기호 등을 별다른 처리없이 바로 사용할 수 있다. 하지만 이런 문자를 포함 시키려는 상황에서 가장 좋은 방법은 {@literal} 태그로 감싸는것이다.

각 문서화 주석의 첫 번째 문장은 해당 요소의 요약 설명(summary description)으로 간주된다. 반드시 대상의 기능을 고유하게 기술하여야 한다. 헷갈리지 않으려면 한 클래스안에서 요약 설명이 똑같은 멤버(혹은 생성자)가 둘 이상이면 안된다. 그리고 마침표(.)에 주의해야 하는데, "머스터드 대령이나 Mrs. 피콕 같은 용의자."라면 첫 마침표가 나오는 "머스터드 대령이나 Mrs."까지만 요약 설명이 된다. 판단 기준은 처음 발견되는 {<마침표><공백><다음문장시작>} 패턴의 마침표 까지다. 이 또한 {@lieral}로 감싸주어 해결이 가능하다.(Java 10부터는 @summary 요약 전용 태그가 있어 깔끔하게 처리가능함)

 

⚠️ 제네릭, 열거타입, 애너테이션의 주의점 

1. 모든 타입 매개변수에 주석을 달아야 한다.
2. 열거 타입을 문서화할 때는 상수들에도 주석을 달아야 한다.
3. 애너테이션 타입을 문서화할 때는 멤버들에도 모두 줙을 달아야 한다.

 

📻 자바독 활용하기

자바독은 프로그래머가 자바독 문서를 올바르게 작성했는지 확인하는 기능을 제공한다. 여기에서 소개한 권장사항 중 상당수를 검사해주는데, Java 7에서는 명령줄에서 -Xdoclint 스위치를 켜주면 활성되고, Java 8 부터는 기본적으로 작동한다.

IDE의 checkstyle같은 플러그인을 사용하면 더 완벽하게 검사가 가능하다. 위에서 말한 지침을 잘 따르면 깔끔하게 API를 설명하는 문서의 작성이 가능하다. 하지만 가장 좋은 방법은 자바독 유틸리티가 생성한 웹페이지를 읽어보는 길뿐이다.

 

문서화 주석은 여러분의 API를 문서화하는 가장 훌륭하고 효과적인 방법이다. 공개 API라면 빠짐없이 설명을 달아야 한다. 표준 규약을 일관되게 지키자. 문서화 주석에 임의의 HTML 태그를 사용할 수 있음을 기억하라. 단 , HTML 메타 문자는 특별하게 취급해야 한다.