이 글에서 분류한 기준은 책의 내용을 바탕으로 주관적인 견해로 재정리해본 것입니다.

주석을 다는 이유

주석은 코드로 의도를 표현하지 못해 사용하는 것이다.

• 주석은 오래될 수록 코드에서 멀어지며, 완전히 그릇될 가능성도 커진다.
  • 주석이 코드의 변화를 딸라가지 못한다.

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

주석을 다는 것이 아니라, 코드를 정리해야 한다.

• 코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.
• 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.

코드로 의도 표현하기

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

좋은 주석과 나쁜 주석

좋은 주석

• 법적인 주석
  • 회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣으라고 명시하는 경우
• 정보를 제공하는 주석
  • 기본적인 정보
  • 가능하다면 함수 이름에 정보를 담는 편이 더 좋다.
• 의도를 설명하는 주석
  • 구현의 의도를 설명한다.
• 의미를 명료하게 밝히는 주석
  • 모호한 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속할 경우, 의미를 명료하게 밝히는 주석이 유용하다.
  • 그릇된 주석을 달아놓을 위험이 상당히 높으므로 주의해야 한다.
• 결과를 경고하는 주석
  • 다른 프로그래머에게 결과를 경고할 목적으로 사용하는 주석이다.
  • ex) 실행 시간이 오래 걸리는 테스트 코드에 주석으로 경고
• TODO 주석
  • ‘앞으로 할 일’
  • 주기적으로 TODO 주석을 점검해서 없애줘야 한다.
• 중요성을 강조하는 주석
  • 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해 사용
• 공개 API에서 Javadocs

나쁜 주석

대다수의 주석이 이 범주에 속한다.

의미 없는 주석

• 주절거리는 주석
  • 이해가 안 되어 다른 모듈까지 뒤져야 하는 주석.
  • 즉, 독자와 제대로 소통하지 못하는 주석을 말한다.
• 같은 이야기를 중복하는 주석
  • 코드 내용을 그대로 중복하는 경우
• 의무적으로 다는 주석
  • ex) 모든 변수에 주석을 달아야 한다는 규칙
• 이력을 기록하는 주석
• 있으나 마나 한 주석
  • 너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석
• 함수나 변수로 표현할 수 있는 주석
• 공로를 돌리거나 저자를 표시하는 주석
• 너무 많은 정보
  • 독자에게 불필요하며 불가사의한 정보

잡음을 주는 주석

• 무서운 잡음
  • Javadocs에서 문서를 제공해야 한다는 잘못된 욕심으로 모든 변수에 주석을 다는 경우
• 위치를 표시하는 주석
  • ex) // Actions /////////////////// 와 같이 구분하는 경우
• 닫는 괄호에 다는 주석
  • 중첩이 심하고 장황한 함수라면 의미가 있을지도 모르지만, 작고 캡슐화된 함수에는 잡음이다.

코드와 주석

• 주석으로 처리한 코드
  • 사용하지 않는 코드는 삭제하라.
• HTML 주석
  • HTML 주석은 읽기 어렵다.
• 전역 정보
  • 코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하지 마라.
• 함수 헤더
  • 짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다.

거짓 정보를 주는 주석

• 오해할 여지가 있는 주석
• 모호한 관계
  • 주석과 주석이 설명하는 코드는 관계가 명백해야 한다.
  • 다시 말해, 코드만으로 설명이 부족할 때 다는 것이 주석이므로, 주석이 다시 설명을 요구하면 안 된다.

Javadocs

• 비공개 코드에서 Javadocs
  • 외부에 공개하지 않을 코드라면 Javadocs를 생성할 필요가 없다.

Reference

참고 서적

📔 Clean Code