[Clean Code] Chapter4. 주석

Clean Code

by. Robert C. Martin

04. 주석

잘 달린 주석은 그 어떤 정보보다 유용하다.
오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨려 해악을 끼친다.

주석은 기껏해야 필요악이다.
주석이 필요하다면, 코드로 의도를 표현하자.

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

• 코드 품질이 나쁘기 때문에 주석을 추가한다.
  • 지저분한 모듈을 깨달았을 때 주석을 다는 것이 아니라 코드를 새로 짜라
• 표현력이 풍부하고 깔끔하고 주석이 거의 없는 코드가, 복잡하고 어수선한 주석 달린 코드보다 낫다.
• 주석을 다는 시간에 깔끔하게 짜는 데 투자해라.

코드로 의도를 표현하라!

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

//직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.falgs & HOURLY_FLAG) && (employee.age > 65 ))

if (employee.isEligibleForFullBenefits())

좋은 주석

• 어떤 주석은 필요하거나 유익하다.
  • 그러나 정말 좋은 주석은 주석을 달지 않을 방법을 찾아낸 주석!

법적인 주석

• 회사가 정립한 구현 표준에 맞췄을 때
• 표준 라이선스 등

정보를 제공하는 주석

• 기본적인 정보를 주석으로 제공한다.
  • 추상 메서드가 반환하는 값을 설명(함수가 의미를 갖는다면 필요없음)
• 정규표현식이 의미하는 바를 설명한다.

의도를 설명하는 주석

• 결정에 깔린 의도를 설명한다.

의미를 명료하게 밝히는 주석

• 인수나 반환 값이 표준 라이브러리나 변경하지 못하는 코드라면 의미를 밝히는 주석이 유용하다.
• 다만 그릇된 주석일 위험이 높다.
  • 필요한 이유면서, 위험한 이유

결과를 경고하는 주석

• 다른 프로그래머에게 결과를 경고할 목적
  • 특정 테스트 케이스를 끌 때

TODO 주석

• 필요하지만 당장 구현하기 어려운 업무를 기술한다.
• TODO를 떡칠한 코드는 좋지 않다.
  • 주기적으로 TODO 주석을 점검해 없애자.

중요성을 강조하는 주석

• 자칫 중요하지 않다고 여겨질 뭔가의 중요성을 강조하기 위해서

공개 API에서 Javadocs

• 설명이 잘 된 공개 API.
  • 표준 자바 라이브러리에서의 Javadocs

---

나쁜 주석

• 대다수의 주석이 나쁜 주석이다.

주절거리는 주석

• 특별한 이유 없이 마지못해 주석을 단다면 시간낭비.
  • 주석을 달기로 했다면 충분한 시간을 들여 최고의 주석을 달도록 해야 한다.
• 이해가 안 되어 다른 모듈까지 뒤져야 하는 주석은 독자와 소통하지 못하는 주석.

같은 이야기를 하는 주석

• 같은 코드 내용을 그대로 중복한다.
  • 주석을 읽는 시간이 코드를 읽는 시간보다 길어진다.

오해할 여지가 있는 주석

• 의도가 좋았으나, 프로그래머가 딱 맞는 주석을 달지 못한다.

의무적으로 다는 주석

• 모든 함수에 Javadocs를 달거나 모든 변수에 주석을 다는 규칙
  • 코드를 복잡하게 만들고, 혼동과 무질서를 초래한다.

이력을 기록하는 주석

• 일종의 기록 혹은 로그
  • 지금은 소스 코드 관리가 가능하니, 제거하자.

있으나 마나한 주석

• 너무나 당연한 사실을 언급하는 주석

함수나 변수로 표현할 수 있다면 주석을 달지 마라

• 주석을 달지 않도록 코드를 개선하는 편이 좋다.

위치를 표시하는 주석

• 특정 위치를 표시하려 주석을 사용한다.
  • 가독성을 낮춘다.
• 드물게 사용하면 주의를 환기시킨다.
  • 남용하면 독자가 잡음으로 여긴다.

닫는 괄호에 다는 주석

• 중첩이 많다면 유용하다.
  • 하지만, 작고 캡슐화된 함수에서는 잡음.
• 닫는 괄호에 주석을 다는 것 보단, 함수를 작게 만들자.

공로를 돌리거나 저자를 표시하는 주석

• 저자 이름으로 코드를 오염시킬 필요가 없다.
  • 오랫동안 방치되어 부정확하고 쓸모없는 정보가 된다.

주석으로 처리한 코드

• 주석 처리된 코드는 이유가 있어 남겨놓은것으로 여겨 지우기를 주저한다.
• 소스 코드 관리 시스템이 우리 대신 코드를 기억해 줄 것이다.

HTML 주석

• HTML 태그를 삽입해야하는 책임은 프로그래머가 아니라 도구가 져야 한다.

전역 정보

• 주석을 달아야 한다면 근처에 있는 코드만 기술하라.
  • 시스템의 전반적인 정보를 기술하지 마라.
• 정보를 수정해도 주석이 변한다는 보장이 없다.

너무 많은 정보

• 역사나 관련 없는 정보를 늘어놓지 마라.

모호한 관계

• 주석과 주석이 설명하는 코드는 둘 사이가 명확해야 한다.

함수 헤더

• 짧은 함수는 긴 설명이 필요 없다.

비공개 코드에서 Javadocs

• 공개 API는 Javadocs가 유용하지만, 공개하지 않을 코드라면 쓸모가 없다.