[클린 코드 리뷰] 주석 4장

로버트 C.마틴의 클린 코드를 읽고 정리한 포스트입니다.

나쁜 코드에 주석을 달지 마라. 새로 짜라

• 브라이언 W. 커니핸, P.J. 플라우거

주석은 언제나 실패를 의미한다. 주석을 달 때마다 자신에게 표현력이 없다는 사실을 푸념해야 마땅하다.

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

코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.

코드로 의도를 표현하라

나쁜 예

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

좋은 예

if (employee.isEligibleForFullBenefits())

좋은 주석

글자 값을 하는 주석을 소개한다. 하지만 정말 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석인 걸 명심해라.

• 법적인 주석 : 각 소스 파일 첫머리에 주석으로 들어가는 저작권 정보와 소유권 정보

  // Copyright (C) ~
  // GNU ~
  

• 정보를 제공하는 주석 : 때로는 기본적인 정보를 주석으로 제공하면 편리하다.
  • 추상 메서드가 반환할 값을 설명하는 주석의 예

    // 테스트 중인 Responder 인스턴스를 반환한다.
    protected abstract Responder responderInstance();
    

  • 때때로 위와 같은 주석이 유용하다 할지라도, 가능하다면 함수 이름에 정보를 담는 편이 더 좋다.

    protected abstract Responder responderBeingTested();
    

• 의도를 설명하는 주석
  • 예) 두 객체를 비교할 때 다른 어떤 객체보다 자기 객체에 높은 순위를 결정했다는 것
  • 예) 스레드를 대량 생성하는 방법으로 어떻게든 경쟁 조건을 만들려 시도했다는 것
• 의미를 명료하게 밝히는 주석
  • 단, 주석이 올바른지 검증하기 쉽지 않다. 이것이 의미를 명료히 밝히는 주석이 필요한 이유인 동시에 주석이 위험한 이유이기도 하다.
  • 아래와 같은 주석을 달 때는 더 나은 방법이 없는지 고민하고 정확히 달도록 각별히 주의한다.

    assertTrue(a.compareTo(a) == 0); // a == a
    

• 알고리즘을 설명하는 주석
  • 알고리즘을 이해하는 데 필요한 주석이라면 달아도 좋다
• 결과를 경고하는 주석
  • 아래와 같은 주석은 요즘에는 @Ignore(“실행이 너무 오래 걸린다.”) 라고 사용할 수 있음

    // 여유 시간이 충분하지 않다면 실행하지 마십시오.
    public void _testWithReallyBigFile()
    {
    ...
    }
    

    // SimpleDateFormat은 스레드에 안전하지 못하다.
    // 따라서 각 인스턴스를 독립적으로 생성해야 한다.
    

• TODO 주석
  • 앞으로 할일은 //TODO 주석으로 남겨두면 편하다
  • 나쁜 코드를 남겨 놓는 핑계가 되어서는 안 된다
  • 주기적으로 TODO 주석을 점검해 없애도 괜찮은 주석은 없애자
• 중요성을 강조하는 주석

  // 여기서 trim은 정말 중요하다. trim 함수는 문자열에서 시작 공백을 제거한다.
  // 문자열에 시작 공백이 있으면 다른 문자열로 인식되기 때문이다.
  

나쁜 주석

• 주절거리는 주석
  • 특별한 이유 없이 의무감으로 마지못해 다는 주석
  • 주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달도록 노력해야 한다
• 같은 이야기를 반복하는 주석
  • 자칫하면 코드보다 주석을 읽는 시간이 더 오래 걸린다
  • 코드보다 부정확해 독자가 함수를 대충 이해하고 넘어가게 만든다
• 오해할 여지가 있는 주석
  • 주석에 담긴 잘못된 정보로 인해 프로그래머가 잘못된 이유를 찾느라 시간을 허비하게 된다
• 의무적으로 다는 주석
  • 모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석다
    • 이러한 주석은 코드를 복잡하게 만들며, 거짓말을 퍼뜨리고, 혼동과 무질서를 초래한다
• 있으나 마나 한 주석
  • 너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못한다
  • 개발자가 주석을 무시하는 습관에 빠지게 되며 결국은 코드가 바뀌면서 주석은 거짓말이 된다
  • 무서운 잡음이 될 수 있다
• 함수나 변수로 표현할 수 있다면 주석을 달지 마라
• 위치를 표시하는 주석
  • 반드시 필요할 때만 사용하자
  • 너무 자주 사용하면 흔한 잡음으로 여겨 무시된다

    // Actions ////////////////////////////
    

• 닫는 괄호에 다는 주석
  • 꼭 주석을 달아야 겠다는 생각이 들면 함수를 줄이려 시도하자

    try {
      ...
    } // try
    catch {
  
    } // catch
  

• 공로를 돌리거나 저자를 표시하는 주석
  • 아래와 같은 정보는 소스 코드 관리 시스템에 저장하는 편이 좋다

    /* 릭이 추가함 */
    

• 주석으로 처리한 코드
  • 주석으로 처리된 코드는 다른 사람들이 지우기를 주저한다
  • 소스 코드 관리 시스템이 우리를 대신해 코드를 기억해준다
  • 필요 없으면 지우자
• HTML 주석
  • 너무 읽기 어렵다
  • Javadocs와 같은 도구로 주석을 뽑아 웹 페이지에 올릴 생각이라면 HTML 태그를 삽입해야 하는 책임은 프로그래머가 아니라 도구가 져야 한다
• 전역 정보
  • 주석을 달아야 한다면 근처에 있는 코드에만 기술하라
  • 코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하지 마라
• 너무 많은 정보
• 모호한 관계
  • 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다
  • 이왕 공들여 주석을 달았다면 적어도 독자가 주석과 코드를 읽어보고 무슨 소린지 알아야 한다
• 함수 헤더
  • 짧은 함수는 긴 설명이 필요 없다
  • 그냥 설명이 필요 없는 좋은 함수가 더 좋다

Previous

‘[클린 코드 리뷰] 함수 3장’ -> Previous

Next

‘[클린 코드 리뷰] 형식 맞추기 5장’ -> Next