Clean Code 4.주석

in Study on Clean Code


나쁜 코드에 주석을 달지 마라. 새로 짜라. - 브라이언 W. 커니핸, P.J. 플라우거

코드는 변화하고 진화한다. 하지만 주석은 언제나 코드를 따라가지 못한다. 그렇게 부정확하게 된 주석은 거짓말을 하게 된다.

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

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

코드로 의도를 표현하라!

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

주석에 쓸 내용으로 함수나 변수 이름을 표현해라.

if (employee.isEligibleForFullBenefits())

좋은 주석

정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이다.

  • 법적인 주석 : 저작권 정보와 소유권 정보
if (employee.isEligibleForFullBenefits())
  • 정보를 제공하는 주석
// 테스트 중인 Responder 인스턴스를 반환
protected abstract Responder responderInstance();

이 경우는 주석이 필요없게 코드를 수정하는 것이 좋다. 함수 이름을 responderBeingTested로 변경할 수 있다.

  • 의도를 설명하는 주석 : 해당 값이 의미하는 것이 무엇인지, 해당 코드를 실행하는 이유가 무엇인지를 설명한다.
// 스레드를 대량 생성하는 방법으로 어떻게든 경쟁 조건을 만들려 시도한다. 
for (int i = 0; i > 2500; i++) {
    WidgetBuilderThread widgetBuilderThread = 
        new WidgetBuilderThread(widgetBuilder, text, parent, failFlag);
    Thread thread = new Thread(widgetBuilderThread);
    thread.start();
}
  • 의미를 명료하게 밝히는 주석 : 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용하다.
  • 결과를 경고하는 주석 : ex. 이 함수는 스레드에 안전하지 못하므로, 각 인스턴스를 독립적으로 생성해야 한다.
// 여유 시간이 충분하지 않다면 실행하지 마십시오.
public void _testWithReallyBigFile() { ... }
  • TODO 주석 : 앞으로 할 일, 당장 정확한 구현이 힘들어서 회피한 경우, 앞으로 필요없는 기능 등… 하지만 주기적으로 //TODO를 점검해서 없에야 한다.
// TODO-MdM 현재 필요하지 않다.
// 체크아웃 모델을 도입하면 함수가 필요 없다.
protected VersionInfo makeVersion() throws Exception {
    return null;
}
  • 중요성을 강조하는 주석 : 필요없는 것처럼 보이지만 삭제하면 안되는 이유를 설명
String listItemContent = match.group(3).trim();
// 여기서 trim은 정말 중요하다. trim 함수는 문자열에서 시작 공백을 제거한다.
// 문자열에 시작 공백이 있으면 다른 문자열로 인식되기 때문이다. 
new ListItemWidget(this, listItemContent, this.level + 1);
return buildList(text.substring(match.end()));
  • 공개API에서 Javadocs

나쁜 주석

대다수 주석

  • 주절거리는 주석 : 주석을 읽은 결과, 그래서 어쩌라고 ? 다른 코드를 뒤져봐야 하나 ?
public void loadProperties() {
    try {
        String propertiesPath = propertiesLocation + "/" + PROPERTIES_FILE;
        FileInputStream propertiesStream = new FileInputStream(propertiesPath);
        loadedProperties.load(propertiesStream);
    } catch (IOException e) {
        // 속성 파일이 없다면 기본값을 모두 메모리로 읽어 들였다는 의미다. 
    }
}
  • 같은 이야기를 중복하는 주석 : 코드 내용을 주석으로 작성. 차라리 코드를 보는게 더 빠르고, 오해의 여지가 없다.
// this.closed가 true일 때 반환되는 유틸리티 메서드다.
// 타임아웃에 도달하면 예외를 던진다. 
public synchronized void waitForClose(final long timeoutMillis) throws Exception {
    if (!closed) {
        wait(timeoutMillis);
        if (!closed) {
            throw new Exception("MockResponseSender could not be closed");
        }
    }
}
  • 오해할 여지가 있는 주석 : 코드의 수행 내용과는 다르게 작성된 주석
  • 의무적으로 다는 주석 : Javadoc을 넣으라는 규칙
/**
 *
 * @param title CD 제목
 * @param author CD 저자
 * @param tracks CD 트랙 숫자
 * @param durationInMinutes CD 길이(단위: 분)
 */
public void addCD(String title, String author, int tracks, int durationInMinutes) {
    CD cd = new CD();
    cd.title = title;
    cd.author = author;
    cd.tracks = tracks;
    cd.duration = durationInMinutes;
    cdList.add(cd);
}
  • 이력을 기록하는 주석 : 소스 코드 관리 시스템이 없을때의 잔재
/*
* 변경 이력 (11-Oct-2001부터)
* ------------------------------------------------
* 11-Oct-2001 : 클래스를 다시 정리하고 새로운 패키징
* 05-Nov-2001: getDescription() 메소드 추가
  ...
*/
  • 있으나 마나 한 주석 : 기본 생성자, 날짜에서 월을 반환한다, 개발자가 분풀이 한 주석 -> 이 경우는 코드를 더 좋게 바꾸자.
/*
 * 기본 생성자
 */
protected AnnualDateRule() { }
  • 무서운 잡음 : Javadoc…
  • 위치를 표시하는 주석 : Banner, Section의 영역을 표시
// Actions /////////////////////////////////////////////
  • 닫는 괄호에 다는 주석 : 대신 함수를 줄이려 시도하자.
  • 저자를 표시 : 소스 코드 관리 시스템이 기억한다.
/* 릭이 추가함 */
  • 주석으로 처리한 코드 : 소스 코드 관리 시스템이 기억해준다. 그냥 지워라.
this.bytePos = writeBytes(pngIdBytes, 0);
//hdrPos = bytePos;
writeHeader();
writeResolution();
//dataPos = bytePos;
if (writeImageData()) {
    wirteEnd();
    this.pngBytes = resizeByteArray(this.pngBytes, this.maxPos);
} else {
    this.pngBytes = null;
}
return this.pngBytes;
  • HTML 주석 : 주석을 렌더링하는 것은 개발자의 책임이 아니라 도구의 책임이다.
  • 전역 정보 : 근처에 있는 코드만 기술해라. 해당 정보가 수정되더라도 다른 파일의 주석까지 고치긴 어렵다.
/**
 * 적합성 테스트가 동작하는 포트: 기본값은 <b>8082</b>.
 *
 * @param fitnessePort
 */
public void setFitnessePort(int fitnessePort) {
    this.fitnewssePort = fitnessePort;
}
  • 너무 많은 정보 (TMI: Too Much Information) : 역사, wikipedia
  • 모호한 관계 : 주석 자체가 다시 설명을 요구하면 안된다.
  • 함수 헤더 : 짧고 한 가지만 수행하며 이름을 잘 붙인 함수에는 해더가 필요없다.
  • 비공개 코드에서 Javadocs

이 글이 도움이 되셨다면 공감 및 광고 클릭을 부탁드립니다 :)