티스토리 뷰

도서/클린 코드

주석

woo'^'chang 2022. 7. 9. 02:19

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

 

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

 

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

 

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

좋은 주석

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

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

나쁜 주석

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

마치며

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

 

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

'도서 > 클린 코드' 카테고리의 다른 글

객체와 자료 구조  (0) 2022.07.12
형식 맞추기  (0) 2022.07.10
함수  (0) 2022.07.07
의미 있는 이름  (0) 2022.07.05
깨끗한 코드  (0) 2022.07.04
댓글
최근에 올라온 글
최근에 달린 댓글
«   2024/11   »
1 2
3 4 5 6 7 8 9
10 11 12 13 14 15 16
17 18 19 20 21 22 23
24 25 26 27 28 29 30
Total
Today
Yesterday