알 수없는 인수로 인한 예외를 문서화하는 모범 사례

Question

이것은 모범 사례 문제에 관한 것입니다. 여기서이 질문을하는 것이 좋습니다. 우리 API의 일부로 사용될 인터페이스를 만들고 있습니다. 나는 getSomeObject()이라는 메서드를 가지고 있으며, 뒤에서 논리를 모으고 SomeObject을 반환합니다. 뒤에는 IllegalArgumentException을 던지는 메서드를 호출하므로 내 getSomeObject() 메서드에서이 예외가 throw 될 수 있습니다. 내가 가진 문제는 API 사용자가 API의 내부 작동에 익숙하지 않아 예외가 던져진 이유를 이해할 수 없다는 것입니다. 인수는 내 메서드 내에서 만들어 지므로 사용자는이 인수가 있는지조차 모릅니다. 문서화를 시도했지만이 예외의 이유는 API 사용자를 혼란스럽게합니다. 그래서 제 질문은 이런 상황에 대해 가장 좋은 방법은 무엇입니까? 이 예외를 문서화하는 올바른 방법은 무엇입니까?

Answer 1

아무런 인수도 취하지 않는 방법으로 IllegalArgumentException을 던지기는 실제로 혼란 스럽습니다.

getSomeObject 외부의 항목이 제대로 정의되지 않은 경우 예외가 발생한다고 생각합니다. 어떻게 당신이 그것을 처리하는 경우, IllegalArgumentException가 던지는 내부 코드의 가능성이 있음을 말할 때

@throws IllegalStateException If member variable xyz is not initialised. 
           This can happen if method `init()` has not been 
           called before `getSomeObject`. 

Answer 2

: 그래서 당신은 어쩌면 IllegalStateException을 던져, 그것은 당신의 javadoc에 대한 설명과 문서 수 있을까?
사용자가 잘못 입력 한 것이 원인입니까?
그렇다면 잡아서 처리해야하며, 던지려면 던져 넣어야합니다. 사용자가 이해할 수있는 예외로 번역되어야합니다.
아니면 그럴 가능성이 희박하며 순전히 이론적입니까?
사용자가 처리해야하는 유효한 예외 시나리오 인 경우 적절한 확인 된 예외를 throw하고 인터페이스에 선언해야합니다.