forked from depromeet/effective-java-study
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[Item74]: 메서드가 던지는 모든 예외를 문서화하라 (depromeet#163)(도모)
- Loading branch information
Showing
1 changed file
with
81 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,81 @@ | ||
# item74. 메서드가 던지는 모든 예외를 문서화하라 | ||
메서드가 던지는 예외는 그 메서드를 사용하는데 아주 중요한 정보다. 따라서 각 메서드가 던지는 예외를 문서화하는 것은 중요하며 충분한 시간을 쏟아야 한다. | ||
|
||
### 검사 예외는 따로따로 선언하자 | ||
검사 예외는 항상 따로따로 선언하고, 각 예외가 발생하는 상황을 자바독의 @throws 태그를 활용해 정확히 문서화 하자.</br> | ||
공통 상위 클래스 하나로 통합해서 선언하는 일은 삼가야 한다. | ||
|
||
극단적인 예로, Exception이나 Throwable을 던진다고 선언해서는 안 된다.</br> | ||
***메서드 사용자에게 각 예외에 대처할 수 있는 힌트를 주지 못할뿐더러, 같은 맥락에서 발생할 수 있는 다른 예외들까지 모두 삼켜버려 API 사용성을 크게 떨어트린다.*** | ||
|
||
### 잘못된 사용 방법 | ||
```java | ||
// 잘못 선언한 예 | ||
public void testMethod() throws Exception { | ||
|
||
} | ||
|
||
// or | ||
|
||
public void testMethod() throws Throwable { | ||
|
||
} | ||
``` | ||
다만, main 메서드는 오직 JVM만이 호출하므로 Exception을 던지도록 선언해도 괜찮다. | ||
|
||
### 올바른 사용 방법 | ||
```java | ||
/** | ||
* @throws IllegalStateException | ||
*/ | ||
public void testMethod(String parameter) throws IllegalStateException { | ||
|
||
} | ||
``` | ||
|
||
### 비검사 예외도 문서화하자 | ||
자바에서 요구하는 것은 아니지만 비검사 예외도 검사 예외처럼 문서화해두면 좋다.</br> | ||
비검사 예외는 일반적으로 프로그래밍 오류를 뜻한다.</br> | ||
따라서 자신이 일으킬 수 있는 오류들이 무엇인지 알려주면 프로그래머는 자연스럽게 오류가 발생하지 않게 코딩하게 된다. | ||
|
||
### public 메서드라면 비검사 예외를 문서화하자 | ||
잘 정비된 비검사 예외의 문서는 그 메서드를 성공적으로 수행하기위한 전제조건이 된다.</br> | ||
public 메서드라면 필요한 전제조건을 문서화해야하며, 그 수단으로 가장 좋은 것이 바로 비검사 예외를 문서화하는 것이다. | ||
|
||
특히, 인터페이스 메서드에서 비검사 예외를 문서화하는 것이 중요하다.</br> | ||
문서화한 전제조건이 인터페이스의 일반 규약에 속하게 되어 그 인터페이스를 구현한 모든 구현체가 일관되게 동작하도록 해주기 때문이다. | ||
|
||
### 비검사 예외는 메서드 선언의 throws 목록에 넣지 말자 | ||
메서드가 던질 수 있는 예외를 @throws로 문서화하되, 비검사 예외는 빼야한다.</br> | ||
검사냐 비검사냐에 따라 API 사용자가 해야 할 일이 달라지므로 이 둘을 확실히 구분해주는게 좋다. | ||
|
||
자바독은 메서드 선언의 throws절에 등장하고 메서드 주석의 @throws 태그에도 명시한 예외와 @throws 태그에만 명시한 예외를 시각적으로 구분해준다.</br> | ||
따라서 프로그래머는 어떤 것이 비검사 예외인지 바로 알 수 있다. | ||
|
||
### 한 클래스의 많은 메서드가 같은 이유로 같은 예외를 던진다면... | ||
한 클래스의 많은 메서드가 같은 이유로 같은 예외를 던진다면 각각에 메서드에 선언하기보다 클래스 설명에 추가하는 방법을 고려하자. | ||
```java | ||
/** | ||
* @throws NullPointerException - 모든 메서드는 param에 null이 넘어오면 NullPointerExcetpion을 던진다. | ||
*/ | ||
class Dummy throws NullPointerException { | ||
|
||
public void methodA(String param) { | ||
... | ||
} | ||
|
||
public void methodB(String param) { | ||
... | ||
} | ||
|
||
public void methodC(String param) { | ||
... | ||
} | ||
} | ||
``` | ||
|
||
### 핵심 정리 | ||
- 메서드가 던질 가능성이 있는 모든 예외를 문서화하자 | ||
- 검사 예외든, 추상 메서드든 구현 메서드든 모두 문서화해야 한다. | ||
- 예외를 문서화할 때는 @throws 태그를 사용하자. | ||
- 검사 예외만 throws 문에 일일이 선언하고, 비검사 예외는 메서드 선언에 기입하지 말자. |