4장 주석
저자는 주석은 코드에 대한 명확성, 표현력 부족으로 인해 사용하게 되는 좋지 못한 습관이라 표현하고있다. 코드를 통해 표현하지 못해 그 부족한 부분을 주석으로 합리화하고 채우려는 습관이라 말한다.
이러한 주석을 써야되는 상황에 도래하면 아래 두개의 질문을 스스로에게 해보아야한다.
상황을 역전해 코드로 의도를 표현할 방법은 없을까?
주석을 달 때마다 자신에게 표현력이 없다는 사실을 푸념해야 마땅하다.
이렇게 저자가 주석에 대해 부정적인 견해를 얘기하는 이유는 무엇일까?
주석을 유지보수 하는것은 불가능에 가깝다.
주석은 너무 자주 거짓말을 한다.
주석을 오래될수록 코드와 멀어진다.
저자는 주석 역시 코드이고 주석을 잘 관리, 유지보수 해야한다는 의견에 동의한다고 한다.
하지만 주석을 유지보수할 시간에 어떻게 하면 주석을 제외한 코드, 그 자체의 표현력을 올릴수있을지
고민하는것이 더 효율적이라 얘기한다.
또 부정확한 주석은 아예 없는것보다 좋지 못하다 라고 얘기하며 두 가지 이유를 댔다.
부정확한 주석은 독자를 현혹하고 오도한다.
더 이상 지킬 필요가 없는 규칙이나 지켜서는 안 되는 규칙을 명시한다.
진실을 오로지 '코드' 에 있다.
코드만이 자기가 하는 일을 진실되게 말한다.
코드만이 정확한 정보를 제공하는 유일한 출처다.
그러므로 우리는 주석을 가능한 줄이도록 꾸준히 노력해야 한다.
위 같은 의견이 다소 강해보일순 있으나 그만큼 주석 사용에 대해 주의해야 한다는 뜻으로 받아들였다.
코드로 의도를 표현하라
Before
// 직원에게 복지 혜책을 받을 자격이 있는지 검사한다.
if ((employee.flags & HOURLY_FLAG) && (employee.age > 65)) { ... }After
if (employee.isEligibleForFullBenefits())위의 코드를 보아도 주석 한줄 보다 코드를 메서드화 하고 의미있는 이름(변수명 ) 을 적어주니 표현력이 풍부해진 코드가 되었다.
좋은 주석
저자는 주석이라도 좋은 주석이 있다고 얘기한다.
법적인 주석
회사에서 정립한 구현 표준에 맞춰 작성하는 주석은 좋은 주석이라 말한다.
ex. 저작권 정보, 소유권 정보
// Copyright (C) 2003,2004 by Object Mentor, Inc. All rights reserved
// GNU General Public License 버전 2 이상을 따르는 조건으로 배포한다.정보를 제공하는 주석
기본적인 정보를 제공하는 주석은 좋은 주석에 속한다.
테스트 중인 Responder 인스턴스를 반환한다.
protected abstract Responder responderInstance();의미를 명료하게 밝히는 주석
모호한 인수나 반환값들을 표현하는 주석은 좋은 주석에 속한다.
assertTrue(a.compareTo(a) == 0); // a == a
assertTrue(a.compareTo(b) != 0); // a != b
assertTrue(ab.compareTo(ab) == 0); // ab == ab
...위 처럼 한눈에 알아보기 힘든 코드도 주석으로 표현해주면 훨씬 표현력이 좋아진다.
하지만 주석이 잘못됬는지 아닌지 증명하는것은 힘들기에 신중을 가해야 할것같다.
결과를 경고하는 주석
코드 관련해서 주의해야할 부분을 알려주는 주석
여유 시간이 충분하지 않다면 실행하지 마십시오.
public void _testWithReallyBigFile() {
writeLinesToFile(10000000);
response.setBody(testFile);
...
}TODO 주석
추후에 해야 할 일들을 적어두는 주석
나쁜 주석
함수나 변수로 표현할 수 있다면 주석을 달지 마라
// 전역 목록 <smodule>에 속하는 모듈이 우리가 속한 하위 시스템에 의존하는가?
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem()))ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem))해당 위에 코드 처럼 주석으로 표현하는것 보다 아래 코드 처럼 주석에서의 의문점, 표현을 코드로 구현하는것이 옳은 방법이다.
같은 이야기를 중복하는 주석
단순히 정보 제공이 아닌 코드를 그대로 읆는 주석은 나쁜 주석이다.
주절거리는 주석
중요도도 떨어지고 정보제공의 의도도 잘 보이지 않는 의무감만 있는 주석은 나쁜 주석이다.
이력을 기록하는 주석, 있으나 마나 한 주석, 주석으로 처리한 코드, 너무 많은 정보 등등 존재한다.
결론
필자도 주석 사용에 있어서 어떠한 기준 없이 사용했던 적이 많다.
이 글을 읽고 작성했던 주석들을 살펴보니 대부분의 주석이 책에서 얘기하는 나쁜 주석에 해당하는 주석이었다.
주로 같은 이야기를 중복해서 하는 주석이 많았다.
코드를 그대로 읽는 주석, 의무감에 썻던 주석이었어서 이번에 새로 수정도 하고 추가적으로 왜 주석이 필요로 했을까? , 왜 주석을 넣으려고 했을까를 고민하면서 리팩토링 해보는 시간을 가지려한다.
Last updated