[클린코드] 4. 주석

목차

1. 주석을 최대한 쓰지 말자.

2. 좋은 주석

3. 나쁜 주석

4. 주석보다 annotation

5. JavaDoc

 

 

 

 

1. 주석을 최대한 쓰지 말자.

프로그래밍 언어를 치밀하게 사용해 의도를 표현할 능력이 있다면, 주석은 거의 필요하지 않다.

대부분 주석 없이는 자신을 표현할 방법을 찾지 못해 할 수 없이 주석을 사용한다.

따라서 코드를 깔끔하게 정리하고 표현력을 강화하는 방향으로 에너지를 쏟아야 한다.

 

코드는 변화하고 진화한다.

주석은 언제나 코드를 따라가지는 않는다.

코드만이 자기가 하는 일을 진실되게 말한다.

따라서 주석을 가능한 줄이도록 꾸준히 노력해야 한다.

 

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

표현력이 풍부하고 깔끔하면 주석이 거의 없는 코드가

복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.

 

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

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

if (employee.isEligibleForFullBenefits())

코드만으로 의도를 분명히 표현할 수 있는 경우라면 주석 대신에 함수를 사용해도 충분하다.

 

2. 좋은 주석

1) 정보를 제공하는 주석

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

정규표현식이 시각과 날짜를 뜻한다고 설명해 구현에 대한 정보를 제공한다.

위와 같은 경우는 클래스를 만들어 함수로 표현하면 주석이 필요 없어진다.

 

2) 의도를 설명하는 주석

// 스레드를 대량 생성하는 방법으로 어떻게든 경쟁 조건을 만들려 시도한다.
for (int i = 0; i < 25000; i++) {
    WidgetBuilderThread widgetBuilderThread =
            new WidgetBuilderThread(widgetBuilder, text, parent, failFlag);
    Thread thread = new Thread(widgetBuilderThread);
    thread.start();
}

 

3) 중요성을 설명하는 주석

// 문자열에 시작 공백이 있으면 다른 문자열로 인식되기 때문에
// trim 함수로 공백을 제거해야 한다.
String listItemContent = match.group(3).trim();

 

4) TODO, FIXME 주석

• TODO : 지금은 해결하지 않지만 나중에 해야할 일을 기술
• FIXME : 문제가 있지만 당장 수정할 필요는 없을 때 기술

IDE에서 하이라이팅 되고 별도의 윈도우에서 볼 수 있다.

 

3. 나쁜 주석

잘못된 정보를 제공하는, 중복 되는 주석은 나쁜 주석이기 떄문에

반듯이 필요한 주석만을 공들여 작성할 필요가 있다.

 

1) 의무적으로 다는 주석

/**
 *
 * @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.duration = duration;
    cdList.add(cd);
}

모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달면

가독성이 떨어지고 잘못된 정보를 제공할 가능성이 높아진다.

 

4. 주석보다 annotation

어노테이션을 사용해서 Class, Method, Field에 대한 정보를 보여줄 수 있고 코드의 실행 흐름에 간섭을 줄 수도 있다.

 

@Deprecated : 컴파일러가 warning을 발생시킨다. 필드나 메소드가 곧 없어짐을 의미하기도 한다.

@NotThreadSafe : Thread Safe하지 않읂을 나타낸다.

 

@Immutable, @Nullable 등 java.lang.annotation 패키지의 어노테이션들을 사용하면

간단하면서 명료하게 주석보다 큰 효과를 얻을 수 있다.

 

5. JavaDoc

Java 코드에서 API 문서를 HTML 형식으로 생성해 주는 도구

IDE에서 Reader Mode로 주석 기호를 삭제하고 텍스트만 확인할 수 있다.

 

1) Class level

 

2) Method level

 

3) Field level

 

 

 

 

 

 

출처

Clean Code(클린 코드) 애자일 소프트웨어 장인 정신 - 로버트 C. 마틴 지음

https://zero-base.co.kr/category_dev_camp/cleancode_1book