[클린 코드] 4장 - 주석

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

코드에 주석을 추가하는 일반적인 이유는 코드의 품질이 나쁘기 때문이다.

차라리 주석을 달지 말고 코드를 정리하자!

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

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

if (employee.isEligibleForFullBenefits())

위의 2개의 코드중 아래의 것이 코드로 의도를 즉각적으로 파악할 수 있다.

코드로 대다수의 의도를 표현할 수 있으며 주석으로 달려는 의도를 함수를 만들어 표현이 가능하다.

3. 좋은 주석

3-1. 법적인 주석

회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석이 필요한 경우가 있다.

// Copyright (C) 2003, 2004, 2005 by Object Mentor, Inc. All rights reserved

3-2. 정보를 제공하는 주석

기본적인 정보를 주석으로 제공하면 편리하다. 예로 추상 메서드가 반환할 값을 설명하는게 있는데 함수의 이름을 통해 정보를 제공하는 것이 더욱 좋다. 정보를 제공하는 주석은 다음과 같이 정규 표현식의 예시 정보를 주는데 사용할 수 있다.

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

3-3. 의도를 설명하는 주석

compareTo() 같은 함수를 보았을 때 우리는 비교해 정렬하는 함수라고 알 수 있다. 하지만 어떤 방식으로 우선순위를 두었는지 코드 작성자의 의도를 한눈에 알기는 힘들다. 따라서 우선순위의 의도를 설명하기 위해서 주석을 사용할 수 있다.

3-4. 의미를 명료하게 밝히는 주석

때떄로 의미가 모호한 인수나 반환값은 그 의미를 주석을 통해 명료하게 밝힐 수 있다.

인수나 반환 값 자체를 명료하게 만드는 것이 좋겠지만 주로 표준 라이브러리라서 변경하지 못하는 코드에 이러한 주석을 적용하면 좋다.

assertTrue(a.compareTo(a) == 0); // a == b
assertTrue(a.compareTo(b) != 0); // a != b

3-5. 결과를 경고하는 주석

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

// 테스트 실행 시간이 다소 오래걸리므로 유의 부탁드립니다.
public void _testWithReallyBigFile() {
...
}

 

3-6. TODO 주석

앞으로 해야 할 일을 //TODO 주석으로 남겨놓으면 편하다.

TODO 주석은 IDE에서 TODO 주석에 대해서 전부를 찾아볼 수 있는 기능을 제공하므로 까먹을 일은 없지만 TODO로 떡칠한 코드는 바람직하지 않으므로 주기적으로 TODO 주석을 지워주어야 한다.

3-7. 중요성을 강조하는 주석

대수롭지 않다고 여겨질 뭔가를 중요성을 강조하기 위해서 주석을 사용하기도 한다.

// trim은 중요하다.
// 해당 메서드에서 trim을 사용하지 않으면 의도치 않은 결과를 반환할 가능성이 있다.
String listItemContent = match.group(3).trim();

3-7. 공개 API에서 Javadocs

공개 API를 구현한다면 Javadocs를 작성하라.

하지만 Javadocs로 인해 사용자에게 그릇된 정보를 제공하는것을 항상 경계하라, 주석또한 코드처럼 관리가 되어야 한다.

4. 나쁜 주석

4-1. 주절거리는 주석

주절거리는 주석은 저자만 이해하고 독자에게 무슨 뜻인지 의미를 전해주지 못하는 주석을 말한다.

특별한 이유 없이 의무감으로, 또는 시키니까 작성하는 주석은 시간낭비이다.

주석을 단다면 좋은 주석을 달도록 노력해야한다.

4-2. 같은 이야기를 중복하는 주석

주석은 코드보다 더 많은 정보를 제공할 수 없다. 어차피 사용자는 코드를 봐야하며 코드의 정당화, 의도나 근거를 설명하는 주석이 아닌이상에야 같은 이야기를 중복하는 주석은 필요가 없다.

/**
 * 이 컴포넌트의 프로세서 지연값
 */
protected int backgroundProcessorDelay = -1;

/**
 * 이 컴포넌트를 지원하기 위한 생명주기 이벤트
 */
protected LifecycleSupport lifecycle = new LifecycleSupport(this);

4-3. 오해할 여지가 있는 주석

때떄로 의도는 좋았으나 프로그래머가 딱 맞을 정도로 엄밀하게 주석을 달지 못하는 경우가 있다.

이 경우 오해가 생길 수 있고 살짝 잘못된 정보로 인해 잘못된 사용을 할 수 있다.

4-4. 의무적으로 다는 주석

모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 좋지않다. 이는 코드를 복잡하게 하며 거짓말을 만들고 무질서를 만든다.

/**
*
* @param title CD 제목
* @param author CD 저자
* @param tracks CD 트랙 숫자 
* @param durationInMinutes CD 길이(단위: 분)
*/
public void addCD(String title, String author, int tracks, int durationInMinutes){

    Cd cd = new CD(); 
    cd.title = title;
    cd.author = author;
    cd.tracks = tracks;
    cd.durationInMinutes = durationInMinutes; 
    cdList.add(cd); 
}

4-5. 이력을 기록하는 주석

모듈을 편집할 때마다 모듈 첫머리에 주석을 기입해 변경을 기록하는 로그를 만드는 경우는 혼란만 제공한다.

하지만 현재는 Git과 같은 코드 관리 시스템이 잘 되어있고 이는 개발자의 기본 소양이다. 소스 코드 관리 시스템을 적극 이용하자.

4-6. 있으나 마나 한 주석

너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석이 있다. 이는 새로운 정보를 제공하지 못한다.

/**
 * 기본 생성자
 */
protected MyStuff() {
}

/**
 * 월 중 일자
 */
private int dayOfMonth;

4-7. 무서운 잡음

때로는 Javadocs도 잡음이 될 수 있다. 문서를 제공해야 한다는 압박과 욕심으로 잡음이 탄생할 수 있다.

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

함수나 변수를 통해 의도를 표현할 수 있다면 주석이 달릴 필요가 없다.

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

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

위의 코드보다 아래의 코드가 주석을 사용하지 않고 의도를 더욱 잘 표현할 수 있다.

4-9. 위치를 표시하는 주석

프로그래머가 소스 파일에서 특정 위치를 표시하려 주석을 사용하는데 이는 가독성을 낮추므로 제거해야 마땅하다. 가끔 사용하여 주의를 환기하는데에는 큰 문제가 없다.

4-10. 닫는 괄호에 다는 주석

닫는 괄호에특수한 주석을 달아 놓으면 중첩이 심한 함수의 파악을 용이하게 할 수 있다. 하지만 작고 캡슐화된 함수는 잡음이므로 최대한 캡슐화된 함수로 쪼개는걸 노력하자.

while() {
...
} // while

4-11. 공로를 돌리거나 저자를 표시하는 주석

Git 과 같은 소스 코드 관리 시스템은 언제 누가 코드를 추가했는지 기억하고 있고 손 쉽게 찾아볼 수 있다. 따라서 이는 코드를 오염시키므로 사용하지 않도록하자.

/** gosiwoo가 작성한 메서드 **/

4-12. 주석으로 처리한 코드

주석으로 코드를 처리한 부분은 다른 프로그래머들이 코드를 지우기를 주저하게 만든다. 소크 코드 관리 시스템은 코드를 기억하고 있음을 누차 설명했으므로 주석으로 코드를 처리해 두지 말자.

InputStreamResponse  response = new InputStreamResponse();
// InputStream resultsStream = formatter.getResultStream();

4-13. HTML 주석

HTML 주석은 소스 코드에서 사용하면 안된다.

HTML 주석은 IDE에서도 읽기 힘들다. 쓰지 말자.

4-14. 전역 정보

주석을 달아야 한다면 근처에 있는 코드만 기술하라.

코드 내부에서 관리할 수 없는 정보를 담고있는 주석은 사용하면 안된다.

/**
 * 적합성 테스트가 동작하는 포트: 기본값은 <b>8082</b>
 *
 * @Param fitnessPort
 */
public void setFitnessPort(int fitnessPort)
{
  this.fitnessPort = fitnessPort;
}

위의 코드에서 포트의 기본값 8082를 관리할 수 있는 코드는 없다. 다른 곳에서 기본 포트값이 바뀌면 해당 주석또한 바뀌어야 한다.