04. 주석

• 주석은 코드로 의도를 설명하지 못해 달게되는 실패의 원인
• 주석을 최신으로 항상 유지하기란 현실적으로 불가능에 가까움
• 필요할지라도 주석은 최대한 줄이는게 좋음

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

• 주석으로 설명하려는 대신 해당 코드를 리팩토링하는데 시간을 투자하자
• 코드로 최대한 의도를 표현하자

좋은 주석

어떤 주석은 정말 필요하거 유익함

• 법적인 주석
• 정보를 제공하는 주석
  • 유용하긴 하지만, 코드로 랩핑해서 의도를 표현할 수 있다면 피하자
• 의도를 설명하는 주석
  • 결정에 깔린 의도까지 설명하기도 함 (테스트코드 예시)
• 의미를 명료하게 밝히는 주석
  • 표준 라이브러리를 사용하나 의미가 명확하게 이해하지 않으면 주석을 달기도함
  • 동시에 주석이 올바른지 검증하기 쉽지 않으니 주석이 위험한 이유가 되기도 함
• 결과를 경고하는 주석
  • 여유시간이 없다면 실행하지 말아야할 테스트 코드 경고를 주석으로 달기도 함
  • 위의 경우 주석이 아니더라도 JUnit 에 @Ignore("시간이 많이 걸림") 으로 무시할 수 있음
• TODO 주석
  • 하지만 나쁜 코드를 남겨놓는 핑계가 되어선 안됨
• 중요성 강조
• 공개 API 의 Javadocs

나쁜 주석

대다수의 경우 나쁜 주석이라 함 ㄷㄷ

• 주절거리는 주석
• 같은 이야기를 중복하는 주석
• 오해할 여지가 있는 주석
• 의무적으로 다는 주석
• 이력을 기록하는 주석 (버전관리 툴로 해결합시다~)
• 있으나 마나 한 주석 (이미 이름이나 문법에서 의도가 보이는 경우)
• 함수나 변수로 표현할 수 있다면 주석 X
• 위치를 표시하는 주석
  • // actions ////////////////// 요런것
• 닫는 괄호에 다는 주석
• 공로 돌리는 주석
• 주석으로 처리한 코드
  • 그냥 삭제하자 (잃어버릴 염려 없다고 약속까지하심 ㅋㅋㅋ)
• HTML 주석
• 전역 정보
• 너무 많은 정보
  • RFC 번호만 붙이면 해당 정보는 검색해보면 됨
• 모호한 관계
• 비공개 코드에서 JavaDocs