♻️[클린코드] #3 주석

 

---

♻️ 주석을 최대한 쓰지 말자

 - 주석은 나쁜 코드를 보완하지 못한다. 

코드에 주석을 추가하는 일반적인 이유 -> 코드 품질이 나쁘기 때문에 설명하려고 주석을 작성하는 경우이다.

주석을 작성할 시간에 코드를 알아듣기 좋게 개선하는데 시간을 보내는 것이 좋다.

 

ex) 코드를 함수로 분리해서, 함수 이름으로 코드의 의도를 표현한다.

 

 - 주석은 방치된다. 

요구사항에 따른 코드의 변화가 생길 때 주석은 따라가지 못한다. 주석은 그저 주석이기 때문에 컴파일 되지 않고 방치된다.

결국 나중에 의미없는 텍스트가 된다.

 

---

♻️ 좋은 주석

주석을 쓸거라면 좋은 주석을 쓰자!

 

 - 구현에 대한 정보를 제공한다. 

출력 포맷에 대한 정보를 제공 ex) 날짜 출력 형식 주석으로 표시

 

 - 의도와 중요성을 설명한다. 

ex) 스레드를 생성하는 함수 : 스레드를 많이 생성하여 시스템에 영향을 끼쳐 테스트하는 의도 설명

ex) trim() 사용 : 유저로부터 입력받은 값을 trim으로 공백제거하는 필요성 설명

-> 다른 사람들이 이해하기 좋다.

 

 -TODO 주석 

지금 당장 해결X, 앞으로 해야할 일 미리 적어둠

IDE에서 하이라이팅되며 별도의 윈도우에서 볼 수 있다.

 

ex) // TODO: 경계값에 대한 테스트 코드 추가하기

 

 -FIXME 주석 

문제가 있지만, 당장 수정할 필요가 없을 때 사용

IDE에서 하이라이팅되며 별도의 윈도우에서 볼 수 있다.

 

ex) // FIXME: 음수일 때 예외 던지기

---

♻️ 주석보다 annotation

 - java.lang.annotation 

annotation : 코드에 대한 메타 데이터

코드의 실행 흐름에 간섭을 주기도 하며, 주석처럼 코드에 대한 정보를 줄 수 있다.

 

@Deprecated : 컴파일러가 warning을 발생시킴

@NotThreadSafe : Thread Safe하지 않음을 나타냄

@Override : 오버라이딩해야함을 의미

---

♻️ JavaDoc

 - JavaDoc 

Java 코드에서 API 문서를 HTML 형식으로 생성해주는 도구

// single line comment (한 줄)

/*
 * regular multi-line comment (여러 줄)
 */

/**
 * 이게 바로 Javadoc
 */

 

 - Class level 

클래스 코드 선언 위에 선언됨.

클래스에 대한 설명 이후상세한 설명

 

@link : 클래스로 linking 할 수 있다.

 

 - Field level 

필드 선언 위에 선언됨.

어떤 필드인지 설명

/**
 * The public name of a hero that is common knowledge
 */
private String heroName;

 

 - Method level 

메서드 선언부 위에 선언됨.

 

<p><a></a></p> 태그로 html 문법 사용 가능

@param : 인자 설명

@return : 리턴값 설명

@see : 참고 설명 ex) <a href="http://www.link_____></a>

@since : 버전 설명 ex) 1.0

 

 -Javadoc 문서 

Javadoc build 명령어를 통해 문서가 만들어진다. (문서화)

 

 -장점 

IDE Reader Mode를 사용하면 슬래쉬( / )가 사라지고 설명만 간단하게 볼 수 있다.

남들에게 코드를 보여줄 때 유용하게 사용가능. 보통 다른 팀에게 자신의 팀의 코드를 보여줄 때 Javadoc으로 정리해서 보여준다.