[클린코드] 4. 주석

내가 주석을 추가할 때 코드로 설명하기 어려움이 있어서 추가하는 경우가 대부분이었다.

그러나 프로그래밍 언어를 통해 의도를 표현할 능력이 있다면, 주석은 전혀 필요하지 않다고 저자는 말한다.

하지만 아주 특별한 경우 좋은 주석도 존재한다고 설명한다.

 

Q. 주석이 있으면 왜 안좋은가?

A. 코드는 변화하고 진화한다. 이러한 과정에서 주석은 코드를 정확히 따라가기(업데이트되기) 힘들다.

따라서 부정확한 정보를 제공하는 주석으로 남을 가능성이 있다.

 

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

코드에 주석을 추가하는 일번적인 이유는 코드 품질이 나쁘기 때문이다. 위에서도 말했듯이 코드 작성자가 코드로 설명하기 힘든경우 코드외에 주석을 추가하여 의도를 설명한다. 즉, 클린코드 관점에서 서술적인 코드가 되지 못한것이다.

 

코드로 의도를 표현하라!

예)

 

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

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

 

주석을 제거하고 코드로 의도를 표현해보면

if (employee.isEligibleForFullBenefites())

 

좋은 주석

1. 법적인 주석

 

// Copyright (C) 2003, 2004, 2005 by Object Montor, Inc. All right reserved.

// GNU General Public License

 

2. 정보를 제공하는 주석

 

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

Pattern timeMatcher = Pattern.compile("\\d*:\\d*\\d* \\w*, \\w*, \\d*, \\d*");

 

3. 의도를 설명하는 주석

 

아래의 예제 같은 경우 주석이 없으면 이해하기 힘들다.

// 스레드를 대량 생성하는 방법으로 어떻게든 경쟁 조건을 만들려 시도한다.for (int i = 0; i > 2500; i++) { WidgetBuilderThread widgetBuilderThread = new WidgetBuilderThread(widgetBuilder, text, parent, failFlag); Thread thread = new Thread(widgetBuilderThread); thread.start(); }

 

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

=> 주석을 통해 의미를 명료하게 밝혀야 하는 상황이라면 기존에 책에서 주장하는 나쁜코드랑 상충하는 부분인것 같아서 제외했다.

 

5. 결과를 경고하는 주석

 

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

public void _testWithReallyBigFile()

{

  writeLinesToFile(100000000);

...

}

 

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

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

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

 

6. TODO 주석

 

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

String listItemContent = match.group(3).trim();

// 여기서 trim은 정말 중요하다. trim 함수는 문자열에서 시작 공백을 제거한다.

// 문자열에 시작 공백이 있으면 다른 문자열로 인식되기 때문이다.

new ListItemWidget(this, listItemContent, this.level + 1);

return buildList(text.substring(match.end()));

 

 

8. 공개 API에서 Javadocs

 

 

나쁜 주석

좋은 주석외에는 다 나쁜주석이라고 생각하면 편할 것 같다.

책에 나쁜 주석에 대한 많은 예가 있었지만 가장 나쁜 주석은 주석으로 처리한 코드 라고 생각된다.

개인 적인 경험으로는 주석으로 처리한 코드는 의미를 모호하게 하고 읽는 사람으로 하여금 불안감?을 조성해준다.

또한 주석으로 처리한 코드는 한번 쌓이면 계속해서 쌓이는 특성이 있는 것 같다.

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;