[클린코드 리뷰] 3. 나쁜 코드에 주석을 달지 마라. 새로 짜라.

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

 주석은 '순수하게 선하지' 못하다. 사실상 주석은 기껏해야 필요악이다. 우리는 코드로 의도를 표현하지 못해, 그러니까 실패를 만회하기 위해 주석을 사용한다. 여기서 내가 실패라는 단어를 썼다는 사실에 주목한다. 진심이다. 주석은 언제나 실패를 의미한다. 때때로 주석 없이는 자신을 표현할 방법을 찾지 못해 할 수 없이 주석을 사용한다.

 그러므로 주석이 필요한 상황에 처하면 곰곰이 생각하기 바란다. 상황을 역전해 코드로 의도를 표현할 방법은 없을까? 코드로 의도를 표현할 때마다 스스로 칭찬해준다. 주석을 달 때마다 자신에게 표현력이 없다는 사실을 푸념해야 마땅하다.

 내가 이렇듯 주석을 무시하는 이유가 무엇이냐고? 거짓말을 하니까. 항상도 아니고 고의도 아니지만 너무 자주 거짓말을 하니까. 주석은 오래될수록 코드에서 멀어진다. 오래될수록 완전히 그릇될 가능성도 커진다. 이유는 단순하다. 프로그래머들이 주석을 유지하고 보수하기란 현실적으로 불가능하니까. 

 

 

주석이 코드에서 분리되어 점점 더 부정확한 고아로 변하는 사례가 너무도 흔하다. 예를들어, 아래에서 주석과 원래 주석을 달았던 행이 어떻게 되었는지 살펴보자.

 

MockRequest request;
private final String HTTP_DATE_REGEXP = 
  "[SMTWF][a-z]{2}\\, \\S[0-9]{2}\\S[jfmasond][A-Z]{2}\\S"+
  "[0-9](4)\\S[0-9]{2}\\:[0-9]{2}\\:[0-9]{2}\\sGMT";
private Response response;
private FitNessContest contest;
private FileResponder responder;
private Locale saveLocale;
// Example: "Tue, 02 Apr 2003 22:18:49 GMT"

 

 짐작컨대, HTTP_DATE_REGEXP 상수와 주석 사이에 다른 인스턴스 변수를 추가했을 가능성이 농후하다. 주석을 엄격하게 관리해야한다고 주장할지도 모르겠다. 하지만 나라면 코드를 깔끔하게 정리하고 표현력을 강화하는 방향으로, 그래서 애초에 주석이 필요 없는 방향으로 에너지를 쏟겠다. 진실은 한곳에만 존재한다. 바로 코드다.

 

 

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

확실히 코드만으로 의도를 설명하기 어려운 경우가 존재한다. 불행히도 많은 개발자가 이를 코드는 훌륭한 수단이 아니라는 의미로 해석한다. 분명히 잘못된 생각이다. 다음 코드 예제 두 개를 살펴보자. 어느 쪽이 더 나은가?

 

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

 

다음 코드는 어떤가?

 

if (employee.isEligibleForFullBenefits())

 

몇 초만 더 생각하면 코드로 대다수 의도를 표현할 수 있다. 많은 경우 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다.

 

 

 

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

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

 

이 코드에서 주석을 없애고 다시 표현하면 다음과 같다.

 

ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem))

 

 

4. 주석으로 처리한 코드

  주석으로 처리한 코드만큼 밉살스러운 관행도 드물다. 다음과 같은 코드는 작성하지 마라! 아래는 아파치 commons에서 가져온 코드다.

 

this.bytePos = writeBytes(pngIdBytes, 0);
//hdrPos = bytePos;
writeHeader();
writeResolution();
//dataPos = bytePos;

 

 두 행을 주석으로 처리한 이유가 무엇일까? 중요해서? 코드를 급박하게 변경헀다는 사실을 알려주려고? 아니면 수년전에 누군가 주석으로 처리한 코드를 아무도 없애지 않아서? 이제는 소스코드 관리 시스템이 우리를 대신해 코드를 기억해준다. 이제는 주석으로 처리할 필요가 없다. 그냥 코드를 삭제하라. 잃어버릴 염려는 없다. 약속한다.

 

 

 

 

 

출처 : 클린코드(애자일 소프트웨어 장인 정신), 로버트 C.마틴