4장. 주석

주석은 기껏해야 필요악 입니다.

프로그래밍 언어를 치밀하게 사용해 의도를 잘 표현할 능력이 있다면 주석은 전혀 필요가 없습니다.

이렇게 주석에 대해 강하게 말하는 이유는 우리는 유지보수를 하며 코드를 자주 변경하게 되는데, 이럴 때마다 주석 또한 같이 바꿔야 하기 때문에 유지보수 할 요소만 늘어나게 됩니다.

또한, 대체로 주석을 변경하지 않아 코드와 주석의 싱크가 맞이 않는 경우도 자주 발생합니다.

즉, 주석은 오히려 코드를 이해하기 어렵게 만드는 요소가 됩니다.

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

주석을 추가하는 이유는 일반적으로 코드 품질이 나쁘기 때문입니다.

난장판인 코드를 주석으로 설명할 시간에 리팩토링을 통해 깔끔한 코드를 만드는데 시간을 더 쏟길 바랍니다.

코드로 의도를 표현하라!

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

if(employee.isEligibleForFullBenefits())

위 예제에서 알 수 있듯, 대부분의 경우 주석으로 다려는 설명을 함수로 만들어 표현해도 충분합니다.

좋은 주석

주석을 달지 않는 것이 제일 좋은 주석이지만 그럼에도 몇 가지 주석은 필요하거나 유익합니다.

법적인 주석

회사가 정립한 구현 표준에 맞춰 법저인 이유로 특정 주석을 넣는 경우

정보를 제공하는 주석

// kk:mm:ss EEE, MMM dd, yyyy 형식이다.
Pattern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\d*, \\d*");

위 처럼 다는 것도 좋지만 이 또한 시각과 날짜를 변환하는 클래스를 만드어 코드를 옮겨주면 주석 없이 깔끔하게 작성할 수 있습니다.

의도를 설명하는 주석

주석은 이 함수가 하려는 의도가 어떤것인지를 알려주는 것이 단순히 구현 과정을 담은 주석보다 좋습니다.

의미를 명로하게 밝히는 주석

일반적으로는 인수나 반환값 자체를 명확하게 만들면 더 좋겠지만, 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용합니다.

결과를 경고하는 주석

때로는 다른 프로그래머에게 결과를 경고할 목적으로 주석을 사용합니다.

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

TODO 주석

필요하다 여기지만 당장 구현하기 어려운 업무를 기술합니다.

• 더이상 필요 없는 기능을 삭제하라는 알림
• 누군가에게 문제를 봐달라는 요청
• 더 좋은 이름을 떠올려달라는 부탁
• 앞으로 발생할 이벤트에 맞춰 코드를 고치라는 주의 등

하지만 너무 남발하는것은 여전히 좋지 않습니다.

중요성을 강조하는 주석

대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해서도 사용됩니다.

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

공개 API에서 Javadocs

공개 API를 개발한다면 반드시 훌륭항 Javadocs를 작성해야합니다.

하지만 여느 주석과 마찬가지로 독자를 오도하거나, 잘못 위치하거나, 그릇된 정보를 전달할 가능성이 존재합니다.

나쁜 주석

대다수의 주석이 여기에 해당합니다.

주절거리는 주석

특별한 이유 없이 의무감으로 혹은 프로세스에서 하라고 하니까 마지못해 주석을 다는 행위는 전적으로 시간낭비입니다.

기왕 주석을 다릭로 했다면 충분한 시간을 들여 최고의 주석을 달도록 노력합시다.

저도 각 필드마다 의무적으로 주석을 단 적이 있었는데, 의미도 없고 코드만 더 알아보기 힘들어 지는것을 겪었습니다.

꼭. 필요할 때만 주석을 달도록 합시다.

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

코드에 이미 의도가 충분히 드러났음에도 똑같은 말을 주석으로 적어놓는 것은 오히려 코드를 이해하는 것을 어렵게 만듭니다.

오해할 여지가 있는 주석

의도는 좋았으나 해당 코드에 딱 맞게 표현하지 못했을수도 있습니다.

이런 경우 오히려 오해가 생겨 코드를 이해하기 더 힘들어 지게 됩니다.

의무적으로 다는 주석

모든 함수에 Javadocs을 달거나 모든 변수에 주석을 다는 것은 오히려 코드를 복잡하게 만들며 혼동을 야기합니다.

있으나 마나 한 주석

모든 변수에 주석을 달다 보면 아주 의미 없는 주석을 달게 됩니다.

// 이름
private String name;

위와 같은 주석이 바로 있으나 마나 한 주석이자 의무적으로 다는 주석일 수 있습니다.

무서운 잡음

떄로는 Javadocs도 잡음입니다.

저자가 주의를 기울이지 않았다면 독자는 혼란에 빠지기 딱 좋습니다.

함수나 변수로 표현할 수 있다면 주석을 달지 마라

여지껏 계속 말한 거지만 네이밍으로 의도를 표현하고 주석은 피하는 것이 좋습니다.

위치를 표시하는 주석

// ======== Actions ======== //

가끔 위처럼 배너 역할을 하는 주석을 달기도 합니다.

너무 자주 사용하지 않는다면 이런 주석은 도움이 되어 좋지만, 자주 사용하게 되면 독자는 잡음으로 느껴 무시하게 되므로 간혹 사용하도록 합시다.

닫는 괄호에 다는 주석

가끔 뎁스가 깊어지면 괄호가 헷갈려 닫는 괄호에 주석을 달곤 합니다.

if() {
	while() {

	} // while
} // if

위 처럼 닫는 괄호에 주석을 달기보다는 작은 함수로 쪼개어 개발하는 것이 좋습니다.

공로를 돌리거나 저자를 표시하는 주석

요즘에는 Git 같은 형상관리를 사용하면 누가 작성했는지 다 나옵니다.

그러니 이런 주석은 의미가 없습니다.

주석으로 처리한 코드

바로 위에서 언급한것과 같이 어차피 Git을 사용하면 버전이 다 관리가 되기 때문에 굳이 주석으로 코드를 남겨둘 필요가 없습니다.

HTML 주석

Javadocs를 사용하면 HTML로 작성하여 문서를 만들곤 합니다.

하지만 HTML은 편집기에서 읽기가 어렵고, 이런 행위는 프로그래머가 아닌 도구가 책임져야할 행위입니다.

HTML로 작성하지 맙시다.

전역 정보

주석을 달아야 한다면 근처에 있는 코드만 기술해야 합니다.

코드 일부에 주석을 달면서 시스템 전반적인 정보를 기술하는 것은 좋지 않습니다.

너무 많은 정보

주석에다 역사나 관련 없는 정보를 장황하게 늘어놓으면 코드를 이해하기 힘듭니다.

코드에 필요한 내용만 작성하는것이 좋습니다.

모호한 관계

주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 합니다.

이왕 공들여 작성할 것이라면 확시하게 작성하세요.

함수 헤더

짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석을 다는것 보다 훨씬 좋습니다.

비공개 코드에서 Javadocs

공개하지 않을 코드라면 Javadocs는 쓸모가 없습니다.

마치며

전체적으로 가능한 주석은 달지말고 변수나 함수의 네이밍을 잘 짓는것이 좋다는 내용이였습니다.

다만, 정말 달아야 한다면 필요한 부분에 필요한 내용만 기술하는 것이 좋다는 내용이였습니다.

Javadocs를 다음 인수인계자를 위한다는 마음으로 떡칠한 경험이 있기에 반성을 많이 하게 되었습니다.