4장 : 주석

*<클린 코드>를 참고하여 작성한 글입니다.

주석

• 주석은 '순수하게 선하지' 못하다.
  • 애초에 주석이 필요 없는 방향으로 에너지를 쏟을 것.
  • 진실은 오로지 '코드' 한 곳에만 존재한다. 코드만이 정확한 정보를 제공하는 유일한 출처이다.
  • 간혹 필요할지라도, 주석을 가능한 줄이도록 꾸준히 노력해야 한다.
• 주석은 나쁜 코드를 보완하지 못한다
  • 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.
• 코드로 의도를 표현하라
  • 많은 경우 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다.
• 좋은 주석
  • 어떤 주석은 필요하거나 유익하다.
  • 법적인 주석 : 저작권 정보, 계약 조건 등
  • 정보를 제공하는 주석 : 기본적인 주석 ex.추상 메서드가 반환할 값. -> 하지만 가능하다면 함수 이름에 정보를 담는 편이 더 좋음.
  • 의도를 설명하는 주석 : 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명함.
  • 의도를 명료하게 밝히는 주석 : 모호한 인수, 반환값 (표준 라이브러리나 변경하지 못하는 코드에 속하는 경우) 하지만, 더 나은 방법이 없는지 고민하고 정확히 달도록 각별히 주의해야 함.
  • 결과를 경고하는 주석
  • TODO 주석 : 주기적으로 점검해 없애도 괜찮으면 없앨 것.
  • 중요성을 강조하는 주석
  • 공개 API에서 Javadocs
• 나쁜 주석
  • 주절거리는 주석 : 이해가 안 되어 다른 모듈까지 뒤져야 하는 주석은 독자와 제대로 소통하지 못하는 주석. 이것은 바이트 낭비임.
  • 같은 이야기를 중복하는 주석
  • 오해할 여지가 있는 주석
  • 의무적으로 다는 주석
  • 이력을 기록하는 주석
  • 있으나 마나 한 주석
  • 무서운 잡음 : 때때로 Javadocs도 잡음임.
  • 함수나 변수로 표현할 수 있다면 주석을 달지 마라
  • 위치를 표시하는 주석
  • 닫는 괄호에 다는 주석
  • 공로를 돌리거나 저자를 표시하는 주석
  • 주석으로 처리한 코드
  • HTML 주석
  • 전역 정보 : 주석을 달아야 한다면 근처에 있는 코드만 기술할 것. 시스템의 전반적인 정보를 기술하지 말 것.
  • 너무 많은 정보
  • 모호한 관계 : 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 함.
  • 함수 헤더
  • 비공개 코드에서 Javadocs