클린 코드) 4장 핵심 정리

4장 주석

- 부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다. 

- 주석을 유지 보수하기란 현실적으로 어렵기에 시간이 지날수록 완전히 그릇될 가능성이 높다. 잘못된 정보를 전달하는 주석이 되는것이다.

- 코드만이 자기가 하는 일을 진실되게 말한다. 코드만이 정확한 정보를 제공하는 유일한 출처다.

- 그러므로 우리는 간혹 필요한 예외적인 상황을 제외하곤 주석을 줄이도록 노력해야 한다.

 

주석은 나쁜 코드를 보완하지 못한다. 코드로 의도를 표현하라!

- 코드에 주석을 다는 이유?? 코드 품질이 나쁘니까. 

- 주석 달 시간에 코드를 고쳐!

- 많은 경우 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다.

 

좋은 주석

- 법적인 주석

- 정보를 제공하는 주석

- 의도를 설명하는 주석

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

   : 인수나 반환값 표현이 모호한 코드. 단, 코드를 고칠 수 있다면 고치는게 우선임.

- 결과를 경고하는 주석 

- TODO 주석

- 중요성을 강조하는 주석

   : 대수롭지 않게 여겨질 수 있는 중요한 무언가를 강조

- 공개 API에서 Javadocs

 

나쁜 주석

- 주절거리는 주석

   : 코드가 구려서 주석을 다는데 주석도 구린 경우. 주석을 달기로 결정했으면 충분한 시간을 들여 견고한 주석 달자.

- 같은 이야기를 중복하는 주석, 있으나 마나 한 주석

   : 주석이 코드보다 더 많은 정보를 제공하지 못한다. 추가적인 정보 제공 못한다. 코드가 주는 정보와 중복인 경우. 

     개발자가 주석을 무시하는 습관에 빠지게 됨.

- 오해할 여지가 있는 주석

- 의무적으로 다는 주석

   : 주석은 선택사항임. 

- 이력을 기록하는 주석, 공로를 돌리거나 저자를 표시하는 주석, 주석으로 처리한 코드

   : 소스 코드 관리 시스템에게 맡겨.

- 함수나 변수로 표현할 수 있다면 주석을 달지 마라

- 위치를 표시하는 주석

   : 코드에서 특정 위치를 표시하는 주석. 배너. 반드시 필요할때 쓰자.

- 닫는 괄호에 다는 주석

   : ex. try{ while{ ... }//while ... }//try 중첩이 심한 함수에선 효과적이겠지만 우리가 지향하는 작고 캡슐화된 함수에는 필요 없음.

- 주석으로 처리한 코드

- HTML 주석

- 전역 정보

   : 주석을 달아야 한다면 근처에 있는 코드만 기술하라. 코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하지 마라.

- 너무 많은 정보 (쓸모 없는 역사, 관련 없는 정보)

- 모호한 관계

   : 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다. 어떤 코드를 보충해주는지 명확하게.

- 함수 헤더

   : 함수 자체가 잘 표현되는게 중요함. 부가 설명이 필요하단것 부터 이미 잘못된 상황임.

- 비공개 코드에서 Javadocs