From 3f54abdcf28eba649e51bd09797ff69dc995a6eb Mon Sep 17 00:00:00 2001 From: kdomo Date: Sun, 10 Sep 2023 20:25:14 +0900 Subject: [PATCH] =?UTF-8?q?[Item74]:=20=EB=A9=94=EC=84=9C=EB=93=9C?= =?UTF-8?q?=EA=B0=80=20=EB=8D=98=EC=A7=80=EB=8A=94=20=EB=AA=A8=EB=93=A0=20?= =?UTF-8?q?=EC=98=88=EC=99=B8=EB=A5=BC=20=EB=AC=B8=EC=84=9C=ED=99=94?= =?UTF-8?q?=ED=95=98=EB=9D=BC=20(#163)(=EB=8F=84=EB=AA=A8)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...34\355\231\224\355\225\230\353\235\274.md" | 81 +++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 "Ch10/item74/\353\251\224\354\204\234\353\223\234\352\260\200_\353\215\230\354\247\200\353\212\224_\353\252\250\353\223\240_\354\230\210\354\231\270\353\245\274_\353\254\270\354\204\234\355\231\224\355\225\230\353\235\274.md" diff --git "a/Ch10/item74/\353\251\224\354\204\234\353\223\234\352\260\200_\353\215\230\354\247\200\353\212\224_\353\252\250\353\223\240_\354\230\210\354\231\270\353\245\274_\353\254\270\354\204\234\355\231\224\355\225\230\353\235\274.md" "b/Ch10/item74/\353\251\224\354\204\234\353\223\234\352\260\200_\353\215\230\354\247\200\353\212\224_\353\252\250\353\223\240_\354\230\210\354\231\270\353\245\274_\353\254\270\354\204\234\355\231\224\355\225\230\353\235\274.md" new file mode 100644 index 0000000..768a2e8 --- /dev/null +++ "b/Ch10/item74/\353\251\224\354\204\234\353\223\234\352\260\200_\353\215\230\354\247\200\353\212\224_\353\252\250\353\223\240_\354\230\210\354\231\270\353\245\274_\353\254\270\354\204\234\355\231\224\355\225\230\353\235\274.md" @@ -0,0 +1,81 @@ +# item74. 메서드가 던지는 모든 예외를 문서화하라 +메서드가 던지는 예외는 그 메서드를 사용하는데 아주 중요한 정보다. 따라서 각 메서드가 던지는 예외를 문서화하는 것은 중요하며 충분한 시간을 쏟아야 한다. + +### 검사 예외는 따로따로 선언하자 +검사 예외는 항상 따로따로 선언하고, 각 예외가 발생하는 상황을 자바독의 @throws 태그를 활용해 정확히 문서화 하자.
+공통 상위 클래스 하나로 통합해서 선언하는 일은 삼가야 한다. + +극단적인 예로, Exception이나 Throwable을 던진다고 선언해서는 안 된다.
+***메서드 사용자에게 각 예외에 대처할 수 있는 힌트를 주지 못할뿐더러, 같은 맥락에서 발생할 수 있는 다른 예외들까지 모두 삼켜버려 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 { + +} +``` + +### 비검사 예외도 문서화하자 +자바에서 요구하는 것은 아니지만 비검사 예외도 검사 예외처럼 문서화해두면 좋다.
+비검사 예외는 일반적으로 프로그래밍 오류를 뜻한다.
+따라서 자신이 일으킬 수 있는 오류들이 무엇인지 알려주면 프로그래머는 자연스럽게 오류가 발생하지 않게 코딩하게 된다. + +### public 메서드라면 비검사 예외를 문서화하자 +잘 정비된 비검사 예외의 문서는 그 메서드를 성공적으로 수행하기위한 전제조건이 된다.
+public 메서드라면 필요한 전제조건을 문서화해야하며, 그 수단으로 가장 좋은 것이 바로 비검사 예외를 문서화하는 것이다. + +특히, 인터페이스 메서드에서 비검사 예외를 문서화하는 것이 중요하다.
+문서화한 전제조건이 인터페이스의 일반 규약에 속하게 되어 그 인터페이스를 구현한 모든 구현체가 일관되게 동작하도록 해주기 때문이다. + +### 비검사 예외는 메서드 선언의 throws 목록에 넣지 말자 +메서드가 던질 수 있는 예외를 @throws로 문서화하되, 비검사 예외는 빼야한다.
+검사냐 비검사냐에 따라 API 사용자가 해야 할 일이 달라지므로 이 둘을 확실히 구분해주는게 좋다. + +자바독은 메서드 선언의 throws절에 등장하고 메서드 주석의 @throws 태그에도 명시한 예외와 @throws 태그에만 명시한 예외를 시각적으로 구분해준다.
+따라서 프로그래머는 어떤 것이 비검사 예외인지 바로 알 수 있다. + +### 한 클래스의 많은 메서드가 같은 이유로 같은 예외를 던진다면... +한 클래스의 많은 메서드가 같은 이유로 같은 예외를 던진다면 각각에 메서드에 선언하기보다 클래스 설명에 추가하는 방법을 고려하자. +```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 문에 일일이 선언하고, 비검사 예외는 메서드 선언에 기입하지 말자. \ No newline at end of file