2023년 4월 18일 작성

Clean Code - 주석 사용하지 않기

좋은 code는 그 자체로 표현력이 풍부한 code입니다.

주석은 필요악

  • 좋은 code는 표현력이 풍부하고 깔끔하며 주석이 거의 없는 code입니다.
    • 복잡하고 어수선하며 주석이 많이 달린 code는 나쁜 code입니다.
  • 주석은 code로 의도를 표현하지 못해서 사용하게 됩니다.
    • 현대 programming 언어들은 그 자체로 표현력이 풍부합니다.
    • programming 언어를 치밀하게 사용해 의도를 표현할 능력이 있다면, 주석은 필요하지 않습니다.
  • 주석은 나쁜 code를 보완하지 않습니다.
    • code가 알아보기 어렵다면 주석을 달기보단, code를 깨끗하게 만드는 것이 낫습니다.
  • 주석은 code의 변화를 따라가지 못합니다.
    • 주석은 오래될수록 code에서 멀어집니다.
    • 하나의 잘못된 주석으로 개발자의 신뢰를 잃으면, 다른 주석도 더는 믿을 수 없게 됩니다.
  • 주석도 code입니다.
    • 잘못된 code는 debugging으로 바로잡을 수 있습니다.
    • 그러나 잘못된 주석은 개발자가 신경쓰지 않으면 바로잡을 수 없습니다.
      • IDE에 주석을 debugging하는 기능은 없습니다.
    • 따라서 불필요한 주석은 없애고, 꼭 필요한 주석은 code라고 생각하고 관리해야 합니다.
/* 좋은 예 */
if (employee.isEligibleForFullBenefits()) { ... }

/* 안 좋은 예 */
// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flags & HOURLY_FLAG) && (employee.age > 65)) { ... }

주석이 필요하거나 유익한 경우

  1. 법적인 주석.
    • 예를 들어, 저작권 정보, 소유권 정보 등.

  2. 정보를 제공하는 주석.

  3. 의도를 설명하는 주석.
    • 의도도 code로 표현하는 것이 가장 좋습니다.
    • code로 개발자의 의도를 전부 전달하기 어려운 경우가 있습니다.
    • 이럴 때는 code는 의미를, 주석은 의도를 표현하도록 합니다.
  4. 의미를 명료하게 밝히는 주석.
    • 인수나 반환 값이 표준 library 또는 변경하지 못하는 code에 속한다면, 주석으로 의미를 밝혀줍니다.

  5. 결과를 경고하는 주석.

  6. TODO 주석.
    • 앞으로 할 일을 // TODO 주석으로 남겨두면, 잊지 않고 작업할 수 있습니다.
    • 그러나 TODO가 너무 많은 code는 바람직하지 않습니다.
      • 주기적으로 TODO 주석을 점검하고, 없애도 괜찮은 주석은 지웁니다.
  7. 중요성을 강조하는 주석.
    • 자칫 대수롭지 않다고 여길 수도 있는 부분의 중요성을 강조하기 위해서 사용하기도 합니다.
  8. 공개 API의 Javadocs.
    • 공개 API는 설명이 필요합니다.

나쁜 주석

  1. 대다수 주석.
    • 주석은 좋은 경우가 거의 없습니다.
    • 예를 들어, 허술한 code를 지탱하는 주석, 엉성한 code의 변명, 미숙한 결정을 합리화하는 주석 등.
  2. 주절거리는 주석.
    • 주석은 독자와 소통해야 합니다.
    • 작성자 뿐만 아니라 다른 사람에게도 의미가 있어야 합니다.
      • 다른 code를 뒤져봐야만 의미를 알 수 있다면, 나쁜 주석입니다.
  3. 같은 이야기를 중복하는 주석.
    • code를 지저분하고 정신없게 만듭니다.

  4. 오해할 여지가 있는 주석.

  5. 의무적으로 다는 주석.
    • 모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 쓸모 없습니다.
      • code를 헷갈리게 만듭니다.
      • 거짓말할 가능성을 높입니다.
      • 잘못된 정보를 제공할 여지를 만듭니다.
  6. 있으나 마나 한 주석.
    • 주석은 새로운 정보를 제공해야 합니다.
      • 당연한 사실을 언급할 필요는 없습니다.

  7. 함수나 변수로 충분히 표현할 수 있는 주석.

  8. 닫는 괄호에 다는 주석.
    • 중첩이 심하고 장황한 함수라면 의미가 있을지도 모르지만, 작고 encapsulation된 함수에는 잡음이 됩니다.
    • 닫는 괄호에 주석을 달아야 한다면, 함수를 줄이는 시도를 하는 것이 더 낫습니다.
    • 예를 들어, try, while의 닫는 괄호 뒤에 // try, // while 주석을 다는 것.
  9. 공로를 돌리거나 작성자를 표시하는 주석.
    • source code management system(ex. git)은 누가 언제 무엇을 추가했는지 알려줍니다.
  10. 주석으로 처리한 code.
    • 주석으로 처리된 code는 다른 사람이 지우기 주저하게 됩니다.
      • 이유가 있고 중요해서 남겨놓았다고 생각합니다.
  11. 전역 정보.
    • 주석을 달아야 한다면 근처에 있는 code에만 기술해야 합니다.
    • code 일부에 주석을 달면서 system의 전반적인 정보를 기술해서는 안 됩니다.
  12. 너무 많은 정보.
    • 독자에게 불필요하고 불가사의한 정보는 오히려 혼란을 줄 수 있습니다.
  13. 모호한 관계.
    • ‘주석’과 ‘주석이 설명하는 code’ 사이의 관계가 명백해야 합니다.
  14. 함수 header.
    • 짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 좋은 함수입니다.
    • 주석으로 header를 추가한 함수는 나쁜 함수입니다.
  15. 비공개 code의 Javadocs.
    • 공개하지 않을 code라면 Javadocs는 유용하지 않습니다.
    • Javadocs 주석이 요구하는 형식으로 인해 보기 싫고 산만해집니다.

Reference

  • Clean Code (도서) - Robert C. Martin
  • 개발자의 글쓰기 (도서) - 김철수

목차