[클린 코드] 주석

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

• 코드에 주석을 추가하는 이유는 코드 품질이 나쁘기 때문
• 주석으로 설명할 시간에 코드를 정리할 것
• 주석 대신 함수 이름을 통해 표현할 수 있다.
  • 주석으로 표현한 코드

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

  • 함수 이름으로 표현

      if(emplyee.isEligibleForFullBenefits())
    

좋은 주석

1. 법적인 주석
   • 회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정한 주석을 넣으라 하는 경우
   • 저작권 정보와 소유권 정보 등
2. 정보를 제공하는 주석
   • 기본적인 정보를 제공하는 주석
   • 메서드 반환 값 등을 알려주는 주석
3. 의도를 설명하는 주석
   • 결정에 깔린 의도를 설명하는 주석
   • 우선 순위를 결정할 때 어떤 유형에 순위를 높게 설정했는지 등
4. 의미를 명료하게 밝히는 주석
   • 모호한 인수나 반환값을 읽기 좋게 표현한 주석
   • ex) assertTrue(a.compareTo(a) == 0); // a == a
   • 옳바르지 못한 내용을 달아놓을 수 있는 위험 존재
   • 이렇게 주석을 달 경우 더 나은 방법이 없는지 고민하고 정확히 달도록 각별히 주의해야한다.
5. 결과를 경고하는 주석
   • 다른 프로그래머에게 결과를 경고할 목적으로 사용하는 주석
   • ex) // 여유 시간이 충분하지 않다면 실행하지 말 것
6. TODO 주석
   • 앞으로 해야할 일을 주석으로 남겨두는 것
7. 중요성을 강조하는 주석
   • 대수롭지 않다 여겨질 코드의 중요성을 강조하기 위해 사용
8. 공개 API에서 Javadocs
   • 공개 API를 구현하는 경우

나쁜 주석

대다수의 주석

1. 주절거리는 주석
   • 특별한 이유 없이 의무감으로 혹은 프로세스에서 하라고 해 다는 주석
   • 예시

      try {
        ...
      }
      catch(IOEException e) {
        // 속성 파일이 없다면 기본값을 모두 메모리로 읽어 들였다는 의미이다.
      }
     

   • 누가 기본값을 읽어 들이는지 다른 코드를 뒤져봐야 한다.
   • 이해가 안되어 다른 모듈까지 뒤져야 하는 주석은 낭비일 뿐
2. 같은 이야기를 중복하는 주석
   • 코드에 적힌 내용을 그대로 중복해 주석으로 작성하는 경우
   • 주석이 코드보다 더 많은 정보를 제공하지 못한다.
3. 오해할 여지가 있는 주석
   • 의도는 좋았으나 엄밀하게 주석을 달지는 못한 경우
   • 주석에 담긴 살짝 잘못된 정보로 인해 다른 프로그래머가 힘들어 질 수 있다…
4. 의무적으로 다는 주석
   • 모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석은 규칙
   • 코드를 복잡하게 만들고 혼란스럽게 만든다.
5. 이력을 기록하는 주석
   • 모듈 첫머리에 변경 이력에 관한 주석을 다는 경우
   • 완전 제거하는 게 답
6. 있으나 마나 한 주석
   • 너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석
   • ex) int dayOfMonth; // 월 중 일자
7. 무서운 잡음
   • 문서를 제공해야한다는 생각으로 작성된 Javadocs

8. 함수나 변수로 표현될 수 있는 주석

9. 위치를 표현하는 주석
   • 소스 파일에서 특정 위치를 표시하려 사용하는 주석
   • ex) // Action //////////////////////////////////
10. 닫는 괄호에 다는 주석
    • 예시

      try{
        while() {
            ...
        } // while
      } // try
      

    • 작고 캡슐화된 함수를 만드는게 더 좋다.
11. 공로를 돌리거나 저자를 표시하는 주석
    • 소스 코드 관리 시스템을 사용하여 저장하자
12. 주석으로 처리한 코드
    • 주석으로 처리된 코드는 다른 사람들이 지우기를 주저한다.
    • 소스코드 관리 시스템이 이전 코드를 다 기억하니 그냥 다 삭제해라

13. HTML 주석

14. 전역 정보
    • 주석은 근처에 있는 코드에만 적어라
15. 너무 많은 정보
    • 주석에 역사나 관련 없는 정보를 길게 적은 주석
    • 독자에게 불필요한 정보일 뿐
16. 모호한 관계
    • 주석과 주석이 설명하는 코드는 둘 사이의 관계가 명백해야 한다.
    • 주석의 내용을 읽어도 이해할 수 없어 다시 설명을 필요로 하게 하면 필요없는 주석일 뿐이다.
17. 함수 헤더
    • 짧고 한가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 효율적
18. 비공개 코드에서 Javadocs
    • 공개하지 않을 코드라면 Javadocs가 쓸모가 없다.