주석은 '순수하게 선하지 못하다!'

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

• 주석은 코드로 의도를 표현하지 못해 즉 실패를 만회하기 위해서 사용하는 것
• 주석은 오래될 수록 코드에서 멀어진다
  -> 코드는 보완하지만 보통 주석은 보완하지 않기 때문에 주석은 거짓말을 하게 됨

개인적으로도 항상 주석을 습관적으로 달곤 했다. 그 이유는 남들이 내 코드를 보았을 때 쉽게 읽을 수 있을거란 자신이 없었기 때문이다.

주석을 달 시간에 코드 자체를 정리하는 습관을 들여야 한다.

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

// 좋은 코드
if (employee.isEligibleForFullBenefits())

2. 좋은 주석

• 하지만 몇몇의 경우는 주석이 필요한 경우가 있다

1. 법적인 주석
   회사가 정립한 구현 표준에 맞춰 법적인 이유로 주석을 넣어야 할 때 (소유권과 같은)

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

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 < 25000; i++) {
	WidgetBuilderThread widgetBuilderThread = new WidgetBuilderThread(widgetBuilider, text, parent, failFlag);
    Thread thread = new Thread(widgetBuilderThread);
    thread.start();
}

4. 의미를 명료하게 밝히는 주석
   일반적으로는 인수나 반환값 자체를 명확하게 하면 더 좋다! 하지만 인수나 반환값이 표준 라이브러리나 변경하지 못한다면 의미를 명료하게 밝히는 것이 좋다

assertTrue(a.compareTo(a) == 0); // a == a
assertTrue(a.compareTo(b) != 0); // a != b
assertTrue(a.compareTo(b) == -1); // a < b
assertTrue(a.compareTo(b) == 1); // a > b

5. 결과를 경고하는 주석
   다른 프로그래머에게 결과를 경고할 때 주석을 사용한다

// 여유 시간이 충분하지 않다면 실행하지 마세요!
public void _testWithReallyBigFile() {
	writeLinesToFile(1000000000);
    .......
}

6. TODO 주석
   앞으로 해야할 일을 주석으로 남겨놓으면 좋다

// TODO-MdM 현재 필요하지 않다!
protected VersionInfo makeVersion() throws Exception {
	return null;
}

7. 중요성을 강조하는 주석
   남이 보기에 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해서 사용하면 좋다

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

3. 나쁜 주석

위의 특수한 경우를 제외한 대다수의 주석이 여기에 속한다

1. 주절거리는 주석
   특별한 이유 없이 그냥 써놓은 주석은 나쁜 주석이다

public void loadProperties() {
    try {
    	...
    }
    catch (IOException e) {
    	...
        // 속성 파일이 없다면 기본값을 모두 메모리로 읽어 들인 것이다
    }
}

2. 같은 이야기를 중복하는 주석
   코드 내용과 똑같은 내용을 중복설명하는 주석
   -> 잘못하면 주석을 읽는 시간이 더 오래 걸릴 수 있기에 유의애햐 한다

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

3. 오해할 여지가 있는 주석
   의도와 달리 프로그래머가 정확하게 생각하지 못해서 전달하지 못할경우 오해를 만들 수 있다
   -> 프로그래머가 생각한 방향처럼 흘러가지 않거나 다른 값이 도출 될 수도 있는 경우 에러를 잡기 더 어렵게 만든다.

4. 의무적으로 다는 주석
   아래와 같은 코드는 오히려 모든 변수에 주석을 달면서 코드를 복잡하게 만들고 혼란을 초래한다

// @param title CD 제목
// @param author CD 저자
// @param tracks CD 트랙 숫자

5. 이력을 기록하는 주석
   모듈을 편집할 때마다 모듈 첫머리에 주석을 추가하는 로그식 주석

// 변경 이력(11-Oct-2001부터)
// ----------------------------
// 11-Oct-2001: 클래스를 다시 정리하고 새로운 패키지인 com.jrefinery.data로 옮김
// 05-Nov-2001: getDescription() 메서드를 추가
// ......

6. 있으나 마나 한 주석
   즉 누구나 아는 너무 당연한 사실을 주석으로 다는 경우

// 기본 생성자
protected AnnualDateRule() {}

// 그 달의 날짜
private int dayOfMonth;

7. 함수나 변수로 표현할 수 있는 경우
   주석을 굳이 달지 않고 함수명이나 변수명으로 충분히 표현이 가능한 경우 코드 자체를 개선하는 편이 좋다

// 나쁜 예
// 전역 목록 <smodule>에 속하는 모듈이 우리가 속한 하위 시스템에 의존하는 가?
if (smodule.getDependSubsystems().contains(SubSysMod.getSubSystem()))

// 좋은 예
ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubsystem))

8. 위치를 표시하는 주석
   가끔 소스파일에서 특정 위치를 표시하려 주석을 사용한다 가끔 사용하면 주의를 환기하지만 남발하다보면 가독성을 낮추는 결과를 초래한다

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

9. 주석으로 처리한 코드
   주석으로 처리한 코드는 다른 사람들이 지우기 뭔가 꺼려져서 계속 방치된다. 방치된 주석 코드들이 쌓이면서 나중에는 걷잡을 수 없게 된다

InputStreamResponse response = new InputSteamReseponse();
response.setBody(formatter.getResultStream(), formatter.getByteCount());
// InputStream ressultStream = formatter.getResultStream();
// StreamReader reader = new StreamReader (resultsStream);

10. HTML 주석
    HTML 주석은 정말 읽기 어렵다

// 적합성 테스트를 위한 과업
// 이 과업은 적합성 테스트를 수행해 결과를 출력한다
// <p/>
// <pre>
// &lt;taskdef name=&quot;execute-fitnesse-test&quot;
// .....