[Clean Code] 4. 주석

[Clean Code] 4. 주석

• 나쁜 코드에 주석을 달지 마라. 새로 짜라 - 브라이언 W. 커니핸, P. J. 플라우거
• 주석은 오래될 수록 코드와 멀어진다
  -> 부정확한 주석이 될 확률이 높다
  -> 아예 없는 주석보다 훨씬 나쁘다!

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

코드로 의도를 표현하라

좋은 주석

• 법적인 주석
  • ex. 각 소스파일 첫머리에 주석으로 들어가는 저작권 정보, 소유권 정보

• 정보를 제공하는 주석
  • ex. 반환 값을 설명하는 주석
  • but, 함수/변수 이름을 바꾸면 주석이 필요 없어진다

• 의도를 설명하는 주석
• 의미를 명료하게 밝히는 주석
  • 표준 라이브러리나 변경하지 못하는 코드를 명료하게 밝히는 주석
  • but, 그릇된 주석을 달 위험이 높다!

• 결과를 경고하는 주석
• 중요성을 강조하는 주석

• TODO 주석
  • 프로그래머가 필요하다 여기지만 당장 구현하기 어려운 업무 기술
  • but, 시스템에 나쁜 코드를 남겨놓는 핑계가 되면 X
  • TODO로 떡칠한 코드는 바람직하지 X -> 없앨 수 있는 것은 없애자

• 공개 API에서 Javadocs
  • 공개 API를 구현한다면, 훌륭한 Javadocs를 작성한다
  • but, 주석과 마찬가지로 그릇된 정보를 전달할 가능성 존재

나쁜 주석

• 주절거리는 주석 -> 판독 불가능
• 오해할 여지가 있는 주석

• 같은 이야기를 중복하는 주석
  • 주석이 코드 내용과 중복 -> 코드보다 주석을 읽는 시간이 더 오래 걸림
• 의무적으로 다는 주석
  • ex. 모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야한다는 규칙
    -> 아무 가치 없는 주석을 만들어냄
    -> 코드를 복잡하게 만듦

• 저자를 표시하는 주석
• 이력을 기록하는 주석
  • ex. 모듈을 편집할 때마다 모듈 첫 머리에 주석 추가하는 것
    -> 이제는 소스 코드 관리 시스템 존재
    -> 완전히 제거하는 것이 좋다

• 함수나 변수로 표현할 수 있으면 주석을 달지 X

• 위치를 표시하는 주석
  • ex. //Action//////////////
    -> 너무 자주 사용하지 않으면, 유용하다
    -> but, 너무 자주 사용하면 가독성 낮춤 (특히, 슬래시(/)로 이어지는 잡음)

• 주석으로 처리한 코드
  -> 사용하지 않는 코드 주석으로 처리하지 X -> 바로 삭제하라

• HTML 주석 -> 혐오 그 자체!

• 전역 정보
  • 코드 일부에 주석을 달면서, 시스템의 전반적인 정보 기술하지 X
    -> 해당 코드는 시스템의 전반적인 정보를 통제하지 X

• 너무 많은 정보
  -> 흥미로운 역사나 관련 없는 정보 늘어놓지 X

• 비공개 코드에서 Javadocs
  -> 공개하지 않을 코드라면, Javadocs가 필요 X