Javadoc에서 사용하는 어구 몇개

Question

javadoc 또는 임의의 API에 자유롭게 @throws을 사용해야합니까? 예를 들어, 내가있는 경우 :

LDAPException 
NullPointerException 
IllegalArgumentException 
Exception 

나는 각각에 대해 @throws를 사용하는 경우, 또는 그냥 @throws Exception 말을해야?

Answer 1

이상적으로 javadoc @throws 절은 실제 메서드 throws 절의 수퍼 집합이어야합니다. 일반적인 I/O 오류가 발생하는 경우

는 예를 들어, 방법 throws IOException 경우, 당신은 단지 상황을 설명하는 @throws IOException이 없을 수 있습니다뿐만 아니라 @throws FileNotFoundException은 (IOException의 서브 클래스는) 그런 일 수있는 이유에 대해 이야기.

throws NullPointerException을 선언하지 않은 경우에도 마찬가지 일 수 있습니다. 확인되지 않은 예외이며 메서드 서명에 작성할 필요가 없으므로 (일반적으로 작성되지는 않음) @throws NullPointerException을 문서화 할 수 있습니다.

해야 할 @throws Exception? 아니요,하지만 더 일반적으로는 throws Exception하지 않아야합니다. 그것은 다른 토론입니다. 그러나 결과적으로, javadoc에서 이런 종류의 나쁜 습관을 반복하는 것은 좋지 않습니다. 그것이 발생할 수있는 다른 예외 사항은 무엇입니까? 그럼 어쨌든 @throws으로 하나씩 문서화하지 않으시겠습니까?

Answer 2

당신이 던진 모든 예외를 문서화해야한다고 생각합니다. 이것은 또한 CheckStyle에 의해 시행되는 규칙입니다. Exception을 문서화하면 모든 예외의 매우 일반적인 수퍼 클래스이므로 API 사용자에게 합당한 정보를 제공하지 않습니다.

그렇기 때문에 레이어 사용자 기술에 예외를 던져야한다고 생각합니다. 예외는 아니며 레이어 기술을 기반으로합니다.

예를 들어 나중에 LDAP에서 다른 것으로 전환하려는 경우 예외가 더 이상 일치하지 않을 수 있습니다. 대신 인터페이스를 변경하지 않고도 구현을 자유롭게 변경할 수 있어야합니다.

Java 플랫폼 내에서 의미있는 예외를 찾을 수없는 경우 ServiceException과 같은 자체 예외를 정의하고 예외 변환을 수행합니다. 즉, 구현 종속 예외를 포착하고 예외를 throw합니다.

NullPointerException은 런타임 예외 (선택하지 않음)입니다. 일반적으로 선언되지 않고 throw되지 않으며 문서화되지 않았습니다. API 내의 일부 구성 요소 (초기화되지 않았거나 널 (null) 매개 변수)에 의해 생성 될 수 있습니다. 두 번째 경우에는 IllegalArgumentException에서 변환 할 수 있으며 문서화 할 수 있습니다.

IllegalArgumentException 또한 런타임 예외이며, 명시 적으로 던질 필요가 없습니다.하지만 던져 버리는 것이 좋은 방법 일 수는 있습니다.