잘 달린 주석은 무엇보다도 유용합니다.
그러나, 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만듭니다. 오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼트립니다.
우리는 코드로 모든 의도를 표현하지 못해, 그러니 실패를 만회하기 위해 주석을 사용합니다.
주석은 언제나 실패를 의미합니다.
의도는 코드만으로 표현될수록 깨끗합니다.
코드는 변화하고 진화합니다. 일부가 여기서 저기로 옮겨지기도 하고, 조각이 나뉘고 갈라지고 합쳐지고를 반복합니다. 주석까지 함께 유지보수되는 경우는 정말 드물고, 언제나 따라가지 않습니다.
부정확한 주석은 아예 없는 주석보다 훨씬 나쁩니다. 부정확한 주석은 독자를 현혹시킵니다.
그러나 진실은 코드에 있습니다. 코드만이 자기가 하는 일을 진실되게 말합니다.
그러므로 우리는 주석을 가능한 줄이도록 꾸준히 노력해야 합니다.
주석은 나쁜 코드를 보완하지 못한다
코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문입니다. 모듈을 짜고 보니 짜임새가 엉망이고 알아먹기 어려워지고, 그를 해결하기 위해 주석을 달고는 합니다.
표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가
복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋습니다.
자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신에
그 난장판을 깨끗이 치우는 데 시간을 보내는 것이 좋습니다!
코드로 의도를 표현하라
확실히 코드만으로 의도를 설명하기 어려운 경우는 존재합니다.
//직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if((employee.flags & 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 responderInstance();이러한 주석이 유용하다 할지라도, 함수 이름에 정보를 담으면 주석이 필요 없어질 것입니다.
responderInstance()가 아니라, responderBeignTested()로 바꾸면 주석은 지워도 되겠습니다.
좋은 주석 : 의도를 설명하는 주석
때때로 주석은 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명합니다.
코드의 주석은 왜 이런 코드가 있는지 이해시켜줍니다.
좋은 주석 : 의미를 명료하게 밝히는 주석
때때로 모호한 인수나 반환값은 그 의미를 읽기 좋게 표현하면 이해하기 쉬워집니다.
인수나 반환값이 표준 라이브러리이거나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 좋습니다.
좋은 주석 : 결과를 경고하는 주석
// 여유 시간이 충분하지 않다면 실행하지 마십시오.
public void _testWithReallyBigFile(){
//...
}다른 프로그래머에게 경고하기 위한 목적으로 주석을 사용합니다. 예를 들어, 위는 특정 테스트 케이스를 꺼야하는 이유를 설명하는 주석입니다.
좋은 주석 : TODO 주석
앞으로 할일을 주석으로 남겨두면 편합니다.
// TODO : (앞으로 할 일)필요하다 여기지만 당장 구현하기 어려운 업무를 기술하면 됩니다.
좋은 주석 : 중요성을 강조하는 주석
대수롭지 않게 여겨질 뭔가의 중요성을 강조하기 위해서도 주석을 사용할 수 있습니다.
나쁜 주석
다음은 나쁜 주석입니다. 일반적으로 대부분의 주석은 허술한 코드를 지탱하거나, 엉성한 코드를 변명하거나, 미숙한 결정을 합리화하는 나쁜 주석입니다.
나쁜 주석 : 주절거리는 주석
특별히 이유 없이 쓰인 주석은 필요 없습니다.
나쁜 주석 : 같은 이야기를 중복하는 주석
// this.closed가 true일 때 반환되는 유틸리티 메서드다.
// 타임아웃에 도달하면 예외를 던진다.
public synchronized void waitForClose(final long timeutMillis)
throws Exception {
if(!closed){
wait(timeoutMillis);
if(!closed)
throw new Exception("MockResponseSender could not be closed");
}
}이런 경우에는 주석이 코드보다 정보를 제공하지 못합니다.
실제 코드보다도 부정확해서 독자가 코드를 대충 읽게 만듭니다.
나쁜 주석 : 오해할 여지가 있는 주석
위의 주석은 오해도 불러일으킵니다.
원래의 코드는 this.closed가 true로 변하는 순간에 메서드가 반환되는 것이 아닌 타임아웃을 기다렸다가도 true가 아니면 예외를 던지는 코드입니다.
나쁜 주석 : 의무적으로 다는 주석
모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석기 그지없습니다.
나쁜 주석 : 이력을 기록하는 주석
과거에는 편집할 때 마다 모듈 첫머리에 주석을 기록하곤 했습니다.
그러나 현재는 소스 코드 관리 시스템이 발전하여 오히려 혼란만 불러일으킵니다. 제거해줍시다.
나쁜 주석 : 있으나 마나 한 주석
너무 당연한 사실을 언급하며 새로운 정보를 주지 못하는 주석은 필요 없습니다.
있으나 마나 한 주석을 달 시간에, 코드를 한번 정리하는 것이 훨씬 나은 프로그래머가 되는 길입니다.
나쁜 주석 : 위치를 표시하는 주석
// Actions //////////////특정 위치를 표기하기 위해서 주석을 표기하는 경우가 있습니다.
물론 유용한 경우가 꽤 있습니다. 그러나, 뒷부분의 슬래시(/)로 이어지는 잡음은 없애는 편이 낫습니다.
나쁜 주석 : 닫는 괄호에 다는 주석
닫는 괄호에 주석을 다는 경우가 있습니다. 중첩이 심하고 장황한 경우라면 필요할 지 모르겠지만,
애초에 중첩을 줄이는 것이 훨씬 낫겠습니다.
물론 요즘은 개발 환경에서 기본으로 제공하는 경우가 많습니다.
나쁜 주석 : 공로를 돌리거나 저자를 표시하는 주석
소스 코드 관리 시스템은 저자를 표시하는 것을 돕습니다.
주석으로 표현할 이유가 없고, 오히려 이런 주석은 혼란만 불러올 것 입니다.
나쁜 주석 : 주석으로 처리한 코드
주석으로 처리한 코드는 엉망을 불러옵니다.
주석으로 처리된 코드는 다른 사람들이 지우기 주저합니다.
깨진유리창의 법칙으로 쓰레기코드들이 점점 쌓이게 됩니다.
이제는 소스 코드 관리 시스템이 우수해서 임시로 남겨둘 이유도 없습니다.
나쁜 주석 : HTML 주석
HTML주석은 쓰레기입니다. 한 눈에 읽혀야 하는 주석인데, 전혀 읽히지 않습니다.
나쁜 주석 : 전역 정보
주석을 달아야 한다면 근체에 있는 코드만 기술해야 합니다.
코드 일부에 있는 주석으로 전반적인 정보를 기술하면 안됩니다.
나쁜 주석 : 너무 많은 정보
주석에다 무의미한 정보를 늘어놓지 마십시오.
나쁜 주석 : 모호한 관계
주석과 주석이 설명하는 코드는 둘 사이의 관계가 명확해야 합니다.
주석이 코드의 내용을 잘 설명해주지는 못할망정, 새로운 의문을 만들어내면 안됩니다.
나쁜 주석 : 함수 헤더
짧은 함수는 긴 설명이 필요 없습니다. 짧고 한 가지만 수행하며, 이름을 잘 붙인 함수는 주석을 필요로 하지 않습니다.
