4장 주석

• 주석에 관한 조언을 정리해뒀다

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

• 주석이 길어질수록 코드가 알아보기 힘들다는 것을 의미
• 주석을 달지 말고 코드를 리팩토링하거나 새로 짜는게 맞지 않나 고려해야 한다

2. 코드로 의도를 표현하라

• 서술형의 긴 주석은 코드로 표현할 수 있다

3. 좋은 주석

• 법적인 주석
  - 저작권이나 소유권 정보

// Copyright (C) 2003 ,2004 ,2005 by Object Mentor, Inc. All rights reserved.
// GNU General Public License 버전 2 이상을 따르는 조건으로 배포한다.

• 기본 정보를 제공하는 주석
  - 기본적인 정보를 주석으로 제공하면 편리하다

//테스트 중인 Responder 인스턴스를 반환한다.
protected abstract Responder responderInstance();

- 하지만 함수 이름에 정보를 담을 수 있다면 함수로 의미전달을 하는게 더 좋다

protected abstract Responder responderBeingTested();

• 의도를 설명하는 주석
  - 구현을 이해하게 도와주는 것을 넘어서 로직에 깔린 의도를 설명한다

public int compareTo(Object o){
		if(o instanceof WikiPagePath){
				WikiPagepath p = (WikiPagePath) o;
				String compressedName = StringUtil.join(names, "");
				String complssedArgumentName = StringUtil.join(p.names, "");
				return compressedName.compareTo(compressedArgumentName);
		}
		return 1;//오른쪽 유형이므로 정렬 순위가 더 높다.
}

• 의미를 명료하게 밝히는 주석
  - 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속하면 의미를 명료하게 밝히는 주석이 유용하다

public void testCompareTo() throws Exception {
    WikipagePath a = PathParser.parse("PageA");
    WikiPagePath ab = PathParser.parse("PageA. PageB");
    Wikipagepath b = PathParser.parse("PageB");
    WikiPagepath aa = PathParser.parse("PageA.PageA");
    WikiPagePath bb = PathParser.parse("PageB. PageB");
    WikipagePath ba = PathParser.parse("PageB. PageA");

    assertTrue(a.compareTo(a) == 0); // a == a
    assertTrue(a.compareTo(b) != 0); // a != b
    assertTrue(ab.compareTo(ab) == 0); // ab == ab
    assertTrue(a.compareTo(b) == -1); // a < b
    assertTrue(aa.compareTo(ab) == -1); // aa < ab
    assertTrue(ba.compareTo(bb) == -1); // ba < bb
    assertTrue(b.compareTo(a) == 1); // b > a
    assertTrue(ab.compareTo(aa) == 1); // ab > aa
    assertTrue(bb.compareTo(ba) == 1); // bb > ba
}

• 결과를 경고하는 주석

//여유 시간이 충분하지 않다면 실행하지 마십시오.
public void _testWithReallyBigFile(){ ... }

public static SimpleDateFormat makeStandardHttpDateFormat(){
		//SimpleDateFormat은 스레드에 안전하지 못하다.
		//따라서 각 인스턴스를 독립적으로 생성해야 한다.
		SimpleDateFormat df = new SImpleDateFormat("EEE, dd MMM yyyy HH:mm:ss z");
		df.setTimeZone(TimeZone.getTImeZone("GMT"));
		return df;
}

• TODO 주석
  - 앞으로 할 일을 todo 주석으로 남겨두면 편하다

//TODO 현재 기본 전략만 반환하고 있다.
//기획팀과 비즈니스로직 성립시 신규 전략 추가가 필요하다.
public Strategy makeStrategy() throws Exception { return new DefaultStrategy(); }

• 중요성을 강조하는 주석

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

나쁜 주석

• 주절거리는 주석
  - 답을 알아내기 위해 다른 코드를 봐야하거나 혼잣말 하듯이 주절거리는 주석은 적지 말자

public void loadProperties()
{
		try{
				String propertiesPath = propertiesLocation + "/" + PROPERTIESJILE;
				FilelnputStream propertiesStream = new FilelnputStream(propertiesPath);
				loadedProperties. load(propertiesStream);				
		}catch(IOException e){
				// 속성 파일이 없다연 기본강올 모두 메모러로 읽어 들였다는 의미다.
		}
}

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

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

• 오해할 여지가 있는 주석

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

• 의무적으로 다는 주석
  - 일관성을 유지하기 위해 주석을 달 필요는 없다
  

• 이력을 기록하는 주석
  - git이나 svn을 사용
  

• 무의미한 주석

• 위치를 표시하는 주석
  - 간혹 특정 배너아래 기능들을 모아놓으면 유용한 경우도있지만 대부분 가독성만 낮춘다
  

• 닫는 괄호에 다는 주석
  - 조건문이나 반복문으로 블럭이 중첩될수록 닫는 괄호에 `//end of while` 과 같이 특수한 주석을 달아놓을 수 있지만 이건 좋은 주석이 아니라 코드의 추상화가 부족한 것이다

  • 괄호가 많아 주석을 달아야겠다면 주석을 다는 대신 추상화를 높혀보자.

• 주석으로 처리한 코드
  - 이유가 있어 남겨놓았을거라 추측하며 남겨두게되면서 비슷한 주석 코드들이 쌓여갈 수 있다
  

• HTML 주석
  - 최악의 주석. 편집기/IDE에서조차 읽기 힘들다.
  

• 전역 정보
  - 코드 일부에 주석을 달면서 시스템의 전반적인 정보(ex: 포트번호)를 기술하지 않는다

  • 코드 일부로는 전역정보를 제어할 수 없기에 다른 어딘가에 있는 전역정보가 변경되더라도 알 수 없고 코드가 변해도 주석이 변하지 않는다

• 너무 많은 정보
  - 주석에 정보를 너무 많이 담는것은 독자에게 불필요하며 불가사의할 뿐이다
  

• 모호한 관계
  - 주석과 주석이 설명하는 코드는 둘 사이가 명확해야 한다. 주석을 보면서 또 해석을 요구하는 상황이 벌어진다면 그것은 나쁜 주석이다
  

• 비공개 코드에서 Javadocs

개인적인 감상

• 길게는 1년 짧게는 3개월 단위로 개발 주체가 바뀌는 어플리케이션의 경우 코드의 일관성을 유지하기가 쉽지 않다고 생각해서 주석을 남기는 편이었는데 처음부터 주석을 남기지 말고 코드를 리팩토링하거나 새로 짜라는 문단이 있었기에 많은 생각을 하게 되었다. 또한 원복을 하기 쉽도록 과거의 소스를 주석으로 남겨놓는 편이었고 오늘도 주석으로 남겨놓았는데 이건 내일 출근해서 바로 수정해야겠다는 생각을 했다.
• 아무런 도움이 되지 않는 주석보다는 도움이 되는 주석이 좋고 궁극적으로는 클린 코드로 애플리케이션을 구성할 수 있도록 조금씩이나마 노력을 해야겠다.