Clean Code 4장

4장 주석

코드로 의도를 표현하지 못해, 주석을 사용한다. 그러므로 주석이 필요한 상황이면, 코드로 의도를 표현할 방법을 찾아야 한다.

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

• 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드 > 복잡하고 어수선하며 주석이 많이 달린 코드
• 주석으로 설명하려 애쓰기 보다는 깨끗한 코드를 짜는 데 시간을 보내라

코드로 의도를 표현하라!

• 주석으로 달려는 설명을 함수로 만들어 표현하자

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

if (employee.isEligibleForFullBenefits())

좋은 주석

• 어떤 주석은 필요하거나 유익하다.
  하지만, 정말로 좋은 주석은 주석을 달지 않을 방법을 찾아낸 주석이다.

법적인 주석

정보를 제공하는 주석

• 추상 메서드가 반환할 값을 설명한다.
  • 함수 이름에 정보를 담으면, 주석이 필요 없어진다.
• 정규표현식이 나타내는 것을 설명한다.

의도를 설명하는 주석

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

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

• 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면, 의미를 명료하게 밝히는 주석이 유용하다.
• 물론 그릇된 주석을 달아놓을 위험은 상당히 높다.
  • 주석이 올바른지 검증하기 쉽지 않다.

결과를 경고하는 주석

• 다른 프로그래머에게 결과를 경고하는 목적
  • 특정 테스트 케이스를 꺼야하는 이유를 설명
    • @Ignore 속성을 이용해 테스트 케이스를 끌 수 있다.
  • 아래는 좋은 예제이다.
    • 프로그램 효율을 높이기 위해 정적 초기화 함수를 사용하려던 프로그래머가 실수를 면할 수 있다.

public static SimpleDateFormat makeStandardHttpDateFormat() {
    // SimpleDateFormat은 스레드에 안전하지 못하다
    // 따라서 각 인스턴스를 독립적으로 생성해야 한다.
    SimpleDateFormat df = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss z");
    df.setTimeZone(TimeZone.getTimeZone("GMT"));
    return df;
}

TODO 주석

• 필요하다 여기지만 당장 구현하기 어려운 업무를 기술한다.
• 주기적으로 TODO 주석을 점검해 없애는 것을 권장한다.

중요성을 강조하는 주석

공개 API에서 Javadocs

나쁜 주석

• 대다수 주석이 이 범주에 속한다.

주절거리는 주석

• 특별한 이유 없이 의무감으로 혹은 프로세스에 의해 마지못해 주석을 다는 경우
• 이해가 되지 않아 다른 모듈까지 뒤져야 하는 주석은 독자와 제대로 소통하지 못하는 주석이다.

같은 이야기를 중복하는 주석

• 같은 코드 내용을 그대로 중복한다.
• 자칫하면 코드보다 주석을 읽는 시간이 더 오래 걸린다.

오해할 여지가 있는 주석

의무적으로 다는 주석

• 코드를 복잡하게 만들며, 거짓말을 퍼뜨리고, 혼동과 무질서를 초래한다.
• 아무 가치가 없다.

이력을 기록하는 주석

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

• 소스 코드 관리 시스템이 없었던 상황에서는 바람직하지만, 지금은 아니다.

있으나 마나 한 주석

• 너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석

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

위치를 표시하는 주석

• 소스 파일에서 // Action ///////////////////와 같은 주석 밑에 특정 기능을 모아놓으면 유용한 경우가 있다.
  • 남용하면 독자가 흔한 잡음으로 생각하고 무시한다.
  • 드물게 사용하면, 눈에 띄며 주의를 환기할 수 있다.

닫는 괄호에 다는 주석

• 중첩이 심하고 장황한 함수라면 의미가 있을 수 있다.
• 작고 캡슐화된 함수에는 잡음이다.
• 닫는 괄호에 주석을 달아야 하는 경우, 함수를 줄이려 시도하자.

주석으로 처리한 코드

• 주석으로 처리된 코드는 다른 사람들이 지우기를 주저한다.
  • 이유가 있어 남겨놓았거나 중요하니깐 지우면 안 된다고 생각한다.
• 소스 코드 관리 시스템이 대신해서 코드를 기억해줄 것이다.

HTML 주석

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

전역 정보

• 근처에 있는 코드만 기술하라.
• 코드 일부에 주석을 달면서 시스템 전반적인 정보를 기술하지 마라.
• 전역 정보를 수정해도 해당 주석이 변하리라는 보장은 전혀 없다.

너무 많은 정보

• 흥미로운 역사나 관련 없는 정보를 장황하게 늘어놓지 마라.

모호한 관계

• 주석과 코드는 둘 사이 관계가 명백해야 한다.

함수 헤더

비공개 코드에서 Javadocs