[Clean Code] 주석

Clean Code를 읽고 내용을 정리한 것입니다.

책 구매하러 가기

주석

코드를 표현하는 대표적인 수단

너무 과신하진 말자. 주석은 오래될수록 코드에서 멀어지며 전혀 다른 의미를 갖게될 수 있다.

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

주석을 추가하는 일반적인 이유는 명백하다.

코드 품질이 나쁘기 때문이다.

주석을 달기보다는 깔끔한 코드를 작성하기 위해 노력하자.

코드에 의도를 담아보자

대다수의 코드에는 개발자의 의도를 충분히 담을 수 있다.

// 1)
if (employee.flags & DEV_FLAG) {
    // Do something...
}

// 2)
if (employee.isDeveloper()) {
    // Do something...
}

위의 코드에서 1과 2 중 어느 코드에 개발자의 의도가 더 잘 담겨 있을까?

주석 대신 메소드 이름에 의도를 담는 편이 이해하기 쉽다.

좋은 주석

주석으로 정보를 제공하자

의도를 담기 어려운 코드도 있을 수 있다.

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

정규표현식은 익숙하지 않으면 한 눈에 살펴보기 어렵다.

이런 경우 주석 한 줄이 개발자의 시간을 절약한다.

의도를 설명하는 주석

// 스레드를 많이 생성하여 시스템에 영향을 끼침
for (int i = 0; i < 25000; i++) {
    SomeThread someThread = ThreadBuilder.builder().build();
}

그냥 보면 왜 스레드를 저렇게 많이 생성하지? 하는 생각이 들 수 있으나

주석 한 줄로 그 의도를 알 수 있다.

의미를 확실하게 밝히는 주석

애매한 매개 변수나 반환값을 설명하기 위해 주석을 사용해보자.

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

명료하게 의미를 밝히면 코드를 해석하기 더 쉽다.

하지만 어려운 로직을 설명하기 위한 주석이 달려있어도 주석이 올바른지 검증하기 어려울 수도 있다.

주석을 달기 전에 더 나은 방법이 없는지 고민해보자.

경고 목적의 주석

// 여유 있을 때만 실행하고 그 이외엔 skip test 옵션 사용하세요.
@Test
public void test() {
    for (int i = 0; i < 100000000; i++) {
        // do something...
    }
}

TODO, FIXME, XXX

특별한 것을 기록하기 위한 주석도 있다.

1. TODO

   • 당장 구현하기 어려운 일
   • 추후 해야할 일
   • 더 좋은 이름으로 바꿔달라는 부탁 등

2. FIXME

   • 문제는 있는데 당장 수정할 필요는 없어서 남김

3. XXX

   • 더 생각해볼 필요가 있는 항목

셋 중 TODO의 사용 빈도가 제일 높다.

요샌 IDE에서 TODO의 위치를 다 찾아주니 추후 진행해야 하는 일이 있으면 꼭 TODO를 기록해놓자.

단, 나쁜 코드를 남겨놓고 너무 어려워서 다음에 하겠다는 핑계의 의미로 TODO는 사용하지 않는다.

중요성 강조

// trim이 없으면 의도와 다르게 동작할 수 있음.
if (StringUtils.isEmpty(userId.trim())) {
    // do something...
}

위의 코드가 사용자의 ID를 검증한다고 가정해보자.

누군가가 악의적으로 앞뒤에 공백을 넣은 코드를 통과시키려고 할 수 있으나, trim을 사용하여 공백을 제거하였다.

그렇기 때문에 trim이 중요하다는 것을 주석에서 말하고 있다.

나쁜 주석

마지못해 다는 주석은 잡담이나 다름없다.

주석을 달아야 한다면, 꼭 필요한 주석만을 남기도록 하자.

try {
    FileInputStream fis = new FileInputStream(filePath);
    loadProperties.load(fis);
} catch (IOException e) {
    // properties 파일이 없으면 기본값이 모두 메모리에 포함되어 있음
}

catch 블록의 주석은 작성자 말고는 이해하기 어려워 보인다.

properties는 어디에 선언되어 있는가? 왜 읽는가?

부가적인 정보를 찾기 위해 관련 코드를 모두 뒤져야만 하기 때문이다.

결국 이 주석은 다른 개발자와 전혀 소통이 되지 않음을 의미한다.

중복되는 주석

public class Foo {
    /**
     * class manager
     */
    public Manager manager;

    /**
     * class cluster
     */
    public Cluster cluster;
}

위의 주석은 과연 영양가가 있는 주석일까?

같은 말을 두 번 하는 것과 다를 바가 없다.