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

우리가 코드를 통해 의도를 표현할 능력이 충분히 있다면, 주석은 필요하지 않다. 그러므로 주석이 필요한 상황이면 코드로 의도를 표현하는 것을 더 생각해야 한다.

또한, 코드는 변화하고 진화한다. 코드들이 나뉘고 합쳐지며 남아있는 주석은 점점 부정확해진다. 가능한 주석을 줄이도록 노력해야 한다.

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

엉망인 코드를 주석으로 설명하려 애쓰는 대신에 코드를 정리해라.

코드로 의도를 표현하라

많은 경우, 주석으로 달려는 설명을 함수(이름으로 의도 표현)로 만들어 표현해도 충분하다.

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

이 주석은 밑처럼 쓰면 코드로 표현이 가능하다.

if (employee.isEligibleForFullBenefits())

좋은 주석

그렇다 해도, 어떤 주석들은 필요하거나 유익하다.

법적인 주석

각 소스 파일 첫머리에 주석으로 들어가는 저작권 정보 등이다.

// Copyright (C) 2003, ....

의도를 설명하는 주석

모호한 인수나 반환값이 변경하지 못하는 상황이라면, 의미를 명료하게 밝히는 주석이 유용하다.

단, 그릇된 주석을 달지 않게 각별히 주의하자.

assertTrue(bb.compareTo(ba) == 1); // bb > ba

결과를 경고하는 주석

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

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

TODO 주석

'앞으로 할 일'을 //TODO 주석으로 남겨두면 편하다. 단, 주기적으로 TODO 주석을 점검하여 수정하고 없앤다.

중요성을 강조하는 주석

대수롭지 않다고 여겨질 뭔가의 증요성을 강조하는 주석은 유용하다.

나쁜 주석

허술한 코드를 지탱하거나, 엉성한 코드를 변명하는 등 대다수는 나쁜 주석에 속한다.

주절거리는 주석

특별한 이유 없이 의무적으로 달바에는 달지 않는게 좋다.

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

같은 이야기를 중복하는 주석은 코드만 지저분하게 만든다.

/**
 * 컨테이너와 관련된 Logger 구현
 */
 protected Log logger = null;
 
/**
 * 관련된 Logger 이름
 */
protected String logName = null;

오해할 여지가 있는 주석

조금이라도 잘못 생각될 정보가 담기지 않게 주의하자.

이력을 기록하는 주석 & 저자를 표시하는 주석

예전에는 바람직한 관례였지만, 이제는 혼란만 가중할 뿐이다.

소스 코드 관리 시스템에 저장하자.

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

코드로 의도를 표현하라!

닫는 괄호에 다는 주석

차라리 함수를 줄이려 시도하자.

try{
   while(True){
      cnt++;
   } //while
} //try

주석으로 처리한 코드

이유가 있어 남겨놓았으리라고 생각들지만, 쓸모 없는 코드가 점차 쌓여간다.

전역 정보

주석을 달아야 한다면 해당 코드에 대해서만 달아라. 이외에 다른 정보(ex. 시스템의 전반적인 정보)를 기술하지 마라.

위의 특별한 상황이 아니면 주석 대신 코드로 의도를 표현하자!

Reference

클린 코드: 애자일 소프트웨어 장인 정신 - 로버트 마틴 지음