잘 쓴 주석은 그 어떤 정보보다 유용하나, 경솔하거나 근거 없는 주석은 코드를 오히려 이해하기 어렵게 만든다.
우리가 프로그래밍 언어를 치밀하게 사용해 의도를 표현할 능력이 된다면, 주석은 전혀 필요하지 않다.
우리는 코드로 의도를 표현하지 못해 실패를 만회하기 위해 주석을 사용한다(주석을 달때마다 자신에게 표현력이 없음을 푸념해야 마땅하다.)
코드는 시간이 지날수록 변화하고 여기 저기로 옮겨지기도 한다. 그러나 주석은 코드를 따라기 못한다.
주석은 오래될수록 코드와 멀어지며 그릇될 가능성이 커진다.(주석을 유지보수하기란 현실적으로 불가능)
코드로 의도를 표현하라
// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flags & HOURLY_FLAG) &&
(employee.age > 65))
if (employee.isEligibleForFullBenefits())
...
좋은 주석 (하지만 주석을 달지 않을 방법을 찾아내보자)
1) 법적인 주석
각 소스 파일 첫머리에 저작권, 코드 소유권 정보를 명시
Copyright (c) 2003,2004 by ~~~~~~~2) 정보를 제공하는 주석
// 테스트 중인 Responder 인스턴스를 반환한다.
protected abstract Responder responderInstance();주석보다는 함수나 변수명으로 정보를 담는 편이 더 좋다.
3) 의도를 설명하는 주석
코드 구현에 깔린 의도을 표현한다..
public int compareTo(Object o){
if(o instanceof WikiPagePath){
....
}
// ~~한 경우에는 우선순위가 높다.
return 1;
}public void testConcurrentAddWidgets() {
...
// 스레드를 대량 생성하는 방법으로 경쟁 조건을 만든다.
for (int i = 0; i < 25000; i++){
new Thread(widgetBuilderThread).start();
}
...
}4) 결과를 경고하는 주석
결과를 경고하는 주석
다른 프로그래머에게 경고할 목적으로 주석을 사용하는 경우에도 유용하게 쓰일 수 있습니다.
// 여유 시간이 충분하지 않다면 실행하지 마십시오.
// 위 주석을 @Ignore, @Disabled로 대체 할수 있따.
public void _testWithReallyBigFile() {
...
}
public static SimpleDateFormat makeStanardHttpDateFormat() {
// SimpleDateFormat은 스레드에 안전하지 못하기 때문에 각 인스턴스를 독립적으로 생성해야 한다.
SimpleDateFormat df = new SimpleDateFormat(".......");
return df;
}
5) TODO 주석
// 앞으로 해야 할 일을 TODO 주석으로 남겨두는 경우에도 유용하게 쓰입니다. 하지만 나쁜 코드를 남겨놓고 나중에 수정한다는 식의 TODO는 좋지 않습니다.
//하지만 너무 많이 쌓이는 것은 바람직하지 않기 때문에 주기적으로 확인하고 미룬 일을 처리하거나 삭제할 필요가 있습니다.
//대부분의 IDE에서는 TODO 주석을 추적하는 기능을 제공한다.
protected VersionInfo makeVersion() {
return null;
}
6) 중요성을 강조한는 주석
String listItemContent = match.group(3).trim();
// 여기서 trim으로 시작공백을 제거함으로써 다른 문자열로 인식될 위험을 제거합니다.
7) 공개 API에서 Javadocs
공개 API를 구현한다면 훌륭한 Javadocs를 작성하라. 다른 주석과 마찬가지로 독자를 혼란시키거ㅏ 잘못된 위치된 주석을 남기지 않도록 주의한다.
나쁜 주석
- 허술한 코드를 지탱
- 엉성한 코드를 변명
- 미숙한 결정을 합리화
1) 주절거리는 주석
특별한 이유 없이 의무감이나 프로세스대로 다는 주석. 주석을 달기로 결정됐다면 충분한 시간을 들여 최고의 주석을 달도록 노력한다.이해가 안되서 다른 모듈까지 뒤져야하는 주석은 독자와 제대로 소통하지 못한 주석이다.
public void loadProperties() {
try {
String propertiesPath = propertiesLocation + "/" + PROPERTIES_FILE;
FileInputStream propertiesStream = new FileInputStream(propertiesPath);
loadedProperties.load(propertiesStream);
} catch (IOException e) {
// 속성 파일이 없다면 기본값을 모두 메모리로 읽어 들였다는 의미다.
}
}
2) 같은 이야기를 반복하는 주석
// 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");
}
}
}P77 톰캣주석
3) 오해할 여지가 있는 주석
this.closed가 true가 된 후 타임아웃까지 기다린후 closed가 true가 아닐때만 예외가 던져진다. (주석과 코드의 내용이 다르다.)
4) 의무적으로 다는 주석
모든 함수 변수에 Javadocs, 주석을 달아야하는 규칙은 어리석다. 이는 코드를 복잡하게 만들고, 거짓말을 퍼뜨리며 혼동과 무질서를 초래한다.
/**
*
* @param title CD 제목
* @param author CD 저자
*/
public addCD(String title, String author) {
...
}
5) 이력을 남기기 위한 주석
대부분의 소스 관리 시스템(GIT, SVN 등)들이 이미 제공하는 기능이다.
* 변경 이력 (11-Oct-2001부터)
* ------------------------------------------------
* 11-Oct-2001 : 클래스를 다시 정리하고 새로운 패키징
* 05-Nov-2001: getDescription() 메소드 추가
* 이하 생략6) 있으나 마나한 주석
너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석
/*
* 기본 생성자
*/
protected AnnualDateRule() {
}
/**/ 월 줄 일자*/
private int dayOfMonth;
7) 함수나 변수로 표현할수 있다면 주석을 달지 마라
// 전역 목록 <smodule>에 속하는 모듈이 우리가 속한 하위 시스템에 의존하는가?
if (module.getDependSubsystems().contains(subSysMod.getSubSystem()))
ArrayList moduleDependencies = smodule.getDependSubSystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem))
8) 특정 코드위치를 표시하는 주석
// Actions /////////////////////////////////////////////배너는 눈에 띄며 주의를 환기시키나 남용하면 독자가 이를 잡음으로 여겨 무시하게 된다.
9) 닫는 괄호에 다는 주석
while/(){
} //while
for(){
}//for닫는 괄호에 주석을 달아야할 정도로 깊이가 있다면 함수의 크기를 줄여보자.
10) 공로를 돌리거나 저자를 표시하는 주석
소스 관리 시스템에서는 누가 언제 무엇을 추ㅏㄱ했는지 기억한다.
11) 주석으로 처리한 코드
주석으로 처리된 코드는 다른 사람들이 지우기를 주저한다. (나중에 필요할수도 있으니?)
필요가 없어지면 코드를 삭제하라. 소스 관리 시스템으로 이를 되살릴수 있다.
12) 전역 정보
주석을 달아야 한다면 근처에있는 코드에 대해서만 기술하라. 시스템 전반적인 정보를 기술하지마라
추후에 시스템 설계가 바뀌었을때 주석이 함께 바뀌지 않을 가능성이 있다.
13) 너무 많은 정보
독자에게 꼭 필요한 정보에 대해서만 주석을 남겨라.
14) 모호한 관계
주석과 주석이 설명하는 코드의 관계가 명백해야한다.
주석의 좋은예
https://github.com/ludwiggj/CleanCode/blob/master/src/clean/code/chapter04/PrimeGenerator.java