CleanCode - 주석

주석

먼저 내 개인적은 생각을 말하면 주석 자체는 나쁘다는 생각을 하지 않는다.
단, 주석을 작성한다는 것은 어딘가 불친절하거나 코드로 설명하기 어려운 무언가가 있다는 것이고 그게 로직이라면 조금 문제의 여지가 있을 수 있다 생각한다.
혹은 잘못된 정보를 제공하는 주석 또한 문제가 있다고 생각한다.
언뜻 보기로는 책에서 주석은 나쁘다고 규정하는 듯 보이지만 특정 조건에서의 주석이 나쁘다고 보는듯 하다.

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

처음 주석은 좋은 주석일지라도, 코드가 변화하며 주석까지 유지보수 하기는 쉽지 않다. 안 그래도 따라가기 쉽지 않은 코드인데 주석까지 나에게 거짓말을 하고 있다면 좋은 얘기가 나올 거 같지 않다.

(개인적으로)어느정도 설명이 필요한 것들만 본문에 적어보려 한다.

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

코드에 주석은 왜 생기는 걸까?
내가 보기에도 알아보기 힘든 로직을 작성했을 때 보완하기 위해 주석을 작성한다.
즉, 코드 품질이 나쁘기 때문이다.
코드 품질이 나쁜데 주석의 품질은 좋게 작성할 수 있을까? 매우 어렵다고 본다. 차라리 주석 잘 작성할 노력으로 코드 품질을 높이자.

코드로 의도를 표현하라

이 글을 읽고 있는 분들 중에 코드로 의도 표현이 어려워서 주석을 통해 표현하려고 하는데 무슨 소리냐? 라고 생각하실 분들이 많을 거 같다.
아래 예시 코드를 보자

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


if (employee.isEligibleForFullBenefits())

좋은 주석

어떤 주석은 필요하다고 한다. 책의 저자는 아래 나열하는 주석을 제외하고 주석을 빼라고 강권한다.

법적인 주석

회사 정보, 저작권 정보, 라이센스 등에 대한 정보는 주석으로 작성하라 한다.

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

정보를 제공하는 주석

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

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

위와 같은 주석은 정보를 제공하기 때문에 괜찮다고 한다.

의도를 설명하는 주석

코드를 작성한 의도 자체를 설명하는 주석은 괜찮다고 한다.

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

위 뜻은 잡설하지 않고 코드로 보는 것이 더 명확하게 이해될 것이다.

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

물론 잘못된 정보를 알려주면 쓸모 없겠다.

결과를 경고하는 주석

특정 기능을 수행했을 때의 결과를 경고할 목적으로 작성하는 주석은 좋다고 한다.
예를 들어 수행이 매우 오래 걸린다거나, 아니면 무시해도 된다거나 하는 등의 주석이다.
요즘엔 프레임워크에 어노테이션 같은 걸로 의도를 설명할 수 있지만, 더 명확하게 작성하는 것도 중요하다고 생각한다.

TODO 주석

미래에 해야 할 일들에 대해 주석으로 남겨두면 편하다.
또한 TODO로 남겨놓은 이유에 대해서 설명하는 것도 나쁘지 않을 거 같다.

나쁜 주석

주절거리는 주석

별 의미없는 주석은 안 다느니만 못 하다. 주석 작성하는 사람, 읽는 사람 모두 시간 낭비다.

오해할 여지가 있는 주석

독자에게 오해할 여지가 있는 주석을 달면 당연히 안 될 것이다.
특정 동작에 있어 절대 발생하지 않을 상황에 대해 주석을 달아놓고 이 상황을 주의해야 한다고 하는 등 어중간한 주석이라 판단되는 주석은 좋지 않아 보인다.