주석

코드를 작성할 때 항상 주석에 대해 고민하곤 합니다. 프로그램 코드가 잘 짜여 있다면 주석이 필요하지 않다고 생각하고 있기 때문입니다. 이번 장을 읽으면서 항상 고민이었던 주석에 대해 깊게 알아가고자 합니다.

 

잘 작성된 주석은 어느 정보보다 유용합니다. 하지만 때로는 실패를 만회하기 위해 주석을 사용합니다. 필자는 주석을 사용했을 때 실패를 의미한다고 말하고 있습니다.

 

주석은 시간이 지날수록 필요 없는 정보가 되어갑니다. 코드는 언제나 변화에 열려있고, 계속해서 변화는 발생합니다. 하지만 주석까지 프로그래머가 유지보수하기에는 현실적으로 불가능합니다. 그 시간에 조금 더 좋은 코드를 위한 생각에 투자하는 것이 현명합니다.

 

진실은 코드에만 존재합니다. 우리는 주석을 가능한 줄이도록 꾸준히 노력해야 합니다.

좋은 주석

유용하거나 필요한 주석도 존재합니다. 대표적인 주석으로는 아래와 같습니다.

• 법적인 주석
  • 저작권 정보와 소유권 정보는 필요하고 타당합니다.
• 정보를 제공하는 주석
• 의도를 설명하는 주석
• 의미를 명료하게 밝히는 주석
  • 표준 라이브러리나 변경하지 못하는 코드라면 주석이 유용합니다.
• 결과를 경고하는 주석
• TODO 주석
• 중요성을 강조하는 주석
• 공개 API에서 Javadocs

나쁜 주석

• 주절거리는 주석
  • 독자와 제대로 소통하지 못하는 주석은 바이트만 낭비합니다.
• 같은 이야기를 중복하는 주석
• 오해할 여지가 있는 주석
• 의무적으로 다는 주석
• 이력을 기록하는 주석
  • 현장실습을 진행했던 회사에서 의무적으로 다는 주석이나 이력을 기록하는 주석을 많이 봐왔습니다. 해당 주석을 달면서도 의아했던 부분이 존재했는데 좋지 않은 주석임을 다시금 느끼게 되었습니다.
• 있으나 마나 한 주석
• 무서운 잡음
• 함수나 변수로 표현할 수 있다면 주석을 달지 마라
• 위치를 표시하는 주석
• 닫는 괄호에 다는 주석
  • 대신 함수를 줄이려고 노력해야 합니다.
• 공로를 돌리거나 저자를 표시하는 주석
  • 위와 같은 정보는 소스 코드 관리 시스템에 저장하는 편이 좋습니다.
• 주석으로 처리한 코드
  • 그냥 코드를 삭제하는 편이 좋습니다.
• HTML 주석
• 전역 정보
• 너무 많은 정보
• 모호한 관계
• 함수 헤더
• 비공개 코드에서 Javadocs
• 예제

마치며

한눈에 보기에도 좋은 주석보다는 나쁜 주석이 많음을 알 수 있습니다. 프로그래머는 주석으로 표현하는 것이 아니라 코드로 표현해야 함을 인지하고 더 좋은 코드를 작성하기 위해 노력해야 할 것입니다.

 

프로그래머가 전달하고자 하는 모든 이야기는 코드에 담겨 있어야 한다는 생각이 들었습니다.