클린 코드 - 4장 주석

클린 코드 4장 주석을 정리합니다!

주석

• 주석은 나쁜 코드를 보완하지 못한다
  • 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가,
    복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.
• 코드로 의도를 표현하라
  • 많은 경우 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다.

좋은 주석

• 법적인 주석 : 법적인 이유로 넣는 특정 주석 (저작권 정보와 소유권 정보 등)
• 정보를 제공하는 주석
  • 때로는 편리함을 제공하지만, 웬만하면 함수 이름에 정보를 담아라
• 의도를 설명하는 주석
• 의미를 명료하게 밝히는 주석
  • 때때로 모호한 인수나 반환값은 그 의미를 읽기 좋게 표현하면 이해하기 쉬워짐
• 결과를 경고하는 주석
• TODO 주석
  • 더 이상 필요 없는 기능을 삭제하라는 알림,
    누군가에게 문제를 봐달라는 요청,
    더 좋은 이름을 떠올려달라는 부탁,
    앞으로 발생할 이벤트에 맞춰 코드를 고치라는 주의 등에 유용
  • 시스템에 나쁜 코드를 남겨 놓는 핑계가 되어서는 안됨
• 중요성을 강조하는 주석
  

나쁜 주석

• 주절거리는 주석
  • 특별한 이유 없이 마지못해 다는 주석은 시간낭비
• 같은 이야기를 중복하는 주석
  • 코드 내용을 그대로 중복한다면 주석 읽는 데에 시간이 더 걸림
  • 실제로 코드보다 부정확해 함수를 대충 이해하게 만듦
• 오해할 여지가 있는 주석
  • 살짝 잘못된 정보로 인해 고생하게 됨
• 의무적으로 다는 주석
  • 코드를 헷갈리게 만듦
  • 거짓말할 가능성을 높임
  • 잘못된 정보를 제공할 여지를 만듦
• 있으나 마나 한 주석
  • 개발자가 주석을 무시하는 습관을 갖게 만듦
• 함수나 변수로 표현할 수 있다면 주석을 달지 마라
• 위치를 표시하는 주석
  • 간혹 유용할 수도 있지만 일반적으로 가독성을 낮춤
• 닫는 괄호에 다는 주석
• 공로를 돌리거나 저자를 표시하는 주석
  • 소스 코드 관리 시스템에 저장하는 편이 좋음
• 주석으로 처리한 코드
  • 지우기를 주저하게 만들어 쓸모 없는 코드를 쌓이게 함
• HTML 주석
• 전역 정보, 근처에 있는 코드만 기술하라
• 너무 많은 정보, 대부분 독자에게 불필요한 정보
• 모호한 관계 : 주석 자체에 설명이 필요하게 하지 마라
• 함수 헤더
  • 짧고 한 가지만 수행하며 이름 잘 붙인 함수가
    주석으로 헤더를 추가한 함수보다 훨씬 좋음
• 비공개 코드에서 Javadocs
  • Javadocs 주석이 요구하는 형식으로 인해 코드만 보기 싫고 산만해짐

출처

Clean Code