[클린코드] 4장 주석

안녕하세요 남갯입니다

오늘은 클린코드 4장 주석에 대해 포스팅 해보려고 합니다.

개발을 하면서 모두들 주석을 다실거라 생각합니다. 잘 달린 주석은 그 어떤 정보보다 유용하고 이상한 주석은 더 이해하기 어렵게 만듭니다.

주석은 우리가 치밀하게 언어에 의도를 표현할 수 있다면 주석은 거의 필요없다고 말합니다. 코드를 표현할 능력이 충분하다면 주석은 거의 필요없다고 합니다.

private final String HTTP_DATE_REGEXP =
        "[SMTWF][a-z]{2}\\,\\s[0-9]{2}\\s[J FMASOND][a-z]{2}\\sM+[0-9]{4}\\s[0-9]{2}\\:[0-9]{2}\\:[0-9]{2}\\sGMT";

private Response response;

private FitNesseContext context;

private FileResponder responder;

private Locale saveLocale;

아마도 HTTP_DATE_REGEXP 라는 상수를 만들고 주석 사이에 다른 인스턴스 변수를 추가했을 가능성이 농후하다. 프로그래머들은

주석을 엄격하게 관리해야 하고 복구성과 관련성과 정확성이 언제나 높아야 한다고 주장한다. 하지만 프로그래머에겐 절도가 필요하다고 한다.

주석을 쓸시간에 코드를 정리하고 표현력을 강화하는 방향으로 작성하여 애초에 주석이 필요 없는 방향으로 에너지를 쏟는다.

불필요한 주석은 아예 없는 주석보다 더 나쁘다.

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

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

코드의 의도를 표현하라

// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.

if ((employee.flags & HOURLY_FLAG) && (employee.age >65))

이런코드 말고 

if (employee.isEligibleForFuUBenefits())

몇초만 더 생각하면 대다수의 의도를 표현 가능하다.

좋은주석

어떠한 주석은 필요하거나 유익하다. 정말로 중요한 주석을 살펴보자

1. 법적인 주석

회사의 소유권을 주장하는 주석들이다.

// Copyright (C) 2003,2004,2005 by Object Mentor, Inc. All rights reserved.

// GNU General Public License 버전 2 이상을 따르는 조건으로 배포한다.

2. 정보를 제공하는주석

//테스트 중인 Responder 인스턴스를 반환한다.

protected abstract Responder responderlnstance();

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

responderBeingTested 라고 바꾸면 주석이 필요없어 진다고 한다.

// kk:mm:ss EEE, MMM dd, yyyy 형식이다.

Pattern timeMatcher = Pattern.compile(

"\\d*:\\d*:\\d* \\W*# \\w* \\d*, \\d*");

시간과 날짜를 뜻하는것을 설명한다. 이런코드는 시각과 날짜를 변환하는 클래스를 만들어 코드를 옮기면 더 좋고 깔끔하다.

3. 의도를 설명하는 주석

때때로 주석은 구현을 이해학 도와주는 선을 넘어서 의도까지 설명해준다고 한다.

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

때때로 모호한 인수나 반환값은 그 의미를 읽기 좋게 하면 이해하기 쉬워진다고 한다.

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

이런 주석들은 도움이 되지만 혹여나 잘못된 주석을 달아놓을수도 있고, 검증하기 쉽지 않다.

5. 결과를 경고하는 주석

// 여유시간이 충분하지 않다면 실행하지 마시오

@Ignore 속성을 이용해 테스트 케이스를 꺼버릴 수 있다. 따라서 @Ignore("실행이 너무 오래걸린다") 라고 쓴다.

public static SimpleDateFormat makeStandardHttpDateFormat()

{

// SimpleDateFormat은 스레드에 안전하지 못하다.

// 따라서 각 인스턴스를 독립적으로 생성해야 한다.

  SimpleDateFormat df = new SimpleDateFormat("EEE# dd MMN yyyy HH:mm:ss z");

  df.setTimeZone(TimeZone.getTimeZone("GMT"));

  return df;

}

프로그램 효율을 높이기 위해 정적 초기화 함수를 사용하려던 열성적인 프로그래머가 주석 덕분에 실수를 면할 수 있다.

//(이펙티브 자바에서 나오는 자주 사용해서 초기화하는 인스턴스의 경우 정적 초기화를 통해 생성한다)

6. TODO 주석

앞으로 할일을 //TODO 주석으로 남겨두면 좋다.

7. 중요성을 강조하는 주석

String listltemContent = match.group(3).trim();
// 여기서 trim은 정말 중요하다. trim 함수는 문자열에서 시작 공백을 제거한다.
// 문자열에 시작 공백이 있으면 다른 문자열로 인식되기 때문이다.
new ListltemWidget(this,listltemContent, this.level + 1);
return buildList(text.substring(match.end()));

8. 공개 API에서 Javadocs

설명이 잘 된 공개 API는 참으로 유용하다.

나쁜주석

대다수의 주석은 이 범주에 속한다고 한다. 허술한 코드의 지탱과 엉성한 코드의 변명과 미숙한 결정을 합리화하는 독백이다.

1. 주절거리는 주석

특별한 이유 없이 의무감으로 혹은 프로세스에서 하라고 하니까 하는것.

즉 이런 주석이다.

// 속성파일이 없다면 기본값을 모두 메모리로 읽어들였다는 의미다.

저자에게만 의미있고 나머지에게는 의미가 전해지지 않는 주석이다.

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

//this .closed 가 true 일 때 반환되는 유틸리티 메서드다.
//타임아웃에 도달하면 예외를 던진다.
public synchronized void waitForClose(finaI long timeoutMillis)
        throws Exception {
    if (!closed) {
        wait(timeoutMillis);
        if (!closed)
            throw new Exception("MockResponseSender could not be closed");
    }
}

위와 같은 주석을 달은 목적은 무엇이며 이 주석은 코드보다 더 좋은 정보를 제공하지 못한다.

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

의도는 좋았어도 딱 맞을정도로 엄밀하게 주석을 달지 못하는것.

4. 의무적으로 다는 주석

모든 함수에 JavaDocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석다고 한다.

5. 이력을 기록하는 주석

모듈을 편집할때마다 모듈 첫 머리에 주석을 추가하는 주석들

6. 있으나 마나 한 주석

// 기본생성자 

// 월중 일자

private void startSending() {
    try {
        doSending();
    } catch (SocketException e) {
        // 정상. 누군가 요청을 멈췄다.
    } catch (Exception e) {
        try {
            response.add(ErrorResponder.makeExceptionString(e));
            response.closeAll();
        } catch (Exception el) {
            // 이게 뭐야!
        }
    }
}

위에껀 괜찮았지만 아래꺼는 의미없는 주석이다.

이전 회사에서  "이게뭐야"와 같은 로그를 작성하는것을 봤었다. 그런 로그를 볼때마다 작성하나 마나인 로그를 왜 해뒀는지

아직도 의문이였는데, 이책에서 속 시원하게 말해준다.

7. 무서운 잡음

때론 Javadocs도 잡음이다. 

/** The name. */
private String name;
/** The version. */
private String version;
/** The licenceName. */
private String licenceName;
/** The version. */
private String info;

실제 저자가 어디서 가져온 코드와 주석인데 마지막 부분에 심지어 잘라넣기를 해서 version이라는 주석을 넣었다

이런 주석은 이익을 얻을만한 내용이 없다.

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

9. 위치를 표시하는 주석

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

이 주석과 같이 /는 제거해야한다. 하지만 너무 자주 사용하지 않으면 괜찮다고 한다

10. 닫는 괄호에 다는 주석

// while end

// try

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

// 릭이 추가함

12. 주석으로 처리한코드

13. html 주석

14. 전역 정보

15. 너무 많은 정보

16. 모호한 관계

/**
 * 모든 픽셀을 담을 만큼 충분한 배열로 시작한다(여기에 필터 바이트를 더한다) .
 * 그리고 헤더 정보를 위해 200바이트를 더한다.
 */
        this.pngBytes =new byte[((this.width +1)*this.height *3)+200];

17. 함수의 헤더