4장 주석

코드만이 자기가 하는 일을 진실되게 말한다.

진실은 코드다 

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

* 주석을 달아야 겠다! (X) -> 코드를 정리해야 한다 (O)

* 자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신에 그 난장판을 치우는 데 시간을 보내라

코드로 의도를 표현하라! 

* 네이밍을 통해 주석으로 달려는 설명을 함수/변수에 녹여낼 수 있다!

좋은 주석

* 법적인 주석

* 정보를 제공하는 주석

//code

위에 제시한 주석은 코드에서 사용한 정규표현식이 시각과 날짜를 뜻한다고 설명한다.

하지만 시각과 날짜를 변환하는 클래스를 만들어 코드를 옮겨주면 주석이 필요 없이 더 깔끔하다.

* 의도를 설명하는 주석

구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명한다.

//code

저자의 의도가 분명히 드러나는 또 다른 Example

//code

* 의미를 명료하게 밝히는 주석

인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 듸미를 명료하게 밝히는 주석이 유용

//code

* 결과를 경고하는 주석

때로 다른 프로그래머에게 결과를 경고할 목적으로 주석을 사용한다.

//code

* TODO 주석

개발자가 필요하지만 당장 구현하기 어려운 업무, 더 이상 필요 없는 기능을 삭제 ...

TODO 로 떡칠한 코드는 바람직 하지 않다.

주기적으로 TODO 주석을 없애라

* 중요성을 강조하는 주석

자칫 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해서 주석을 사용

* 공개 API 에서 Javadocs

공개 API 를  개발한다면 꼭 훌륭한 Javadocs 를 작성한다.

나쁜 주석

* 주절거리는 주석