좋은 코드 주석은 어떻게 쓰는 걸까?

이번 포스팅에서는 코드 주석의 중요성과 코드 주석을 잘 쓰는 방법을 알아봅니다. 코드에 남기는 주석은 개발자에게 가장 기본적인 콘텐츠 유형입니다. 이는 ‘자신이 작성한 코드가 하는 일’을 설명하는 걸 넘어서 설계 결정 사항과 트레이드 오프 등 고민 사항을 문서화합니다. 이로써 ‘코드 작성자가 무슨 일을 했고, 왜 그렇게 했는지’ 설명해 줍니다.

코드 주석이 왜 중요한가요?

앞서 설명했듯 코드 주석은 ‘개발자가 작성한 코드가 무엇을 하는지’ 설명하는 콘텐츠입니다. 이는 과거 코드 작성 과정에서 내린 결정의 맥락을 공유하는 데 도움이 됩니다. 또 코드만으로 표현하기 어려운 코드 정보를 전달하는 이점도 있습니다. 코드 주석이 중요한 이유를 각각 자세히 살펴보겠습니다.

복잡한 코드를 이해하는 징검다리

복잡한 코드 앞에 달린 인라인 코드 주석은 나중에 코드를 볼 다른 개발자의 시간을 절약해 줍니다. 프로젝트가 발전할수록 과거에 내린 코드 결정의 맥락을 남겨야 다른 개발자에게 도움이 됩니다. 특히 코드가 복잡하면 앞에 한 줄짜리 인라인 코드 주석이라도 있어야 합니다. 그래야 다른 개발자가 코드를 파악하는 시간을 많이 아낄 수 있습니다.

아래와 같이 주석을 달면 세부적인 내용을 몰라도 코드를 쉽게 이해할 수 있습니다.

java

public static List&lt;Integer&gt; findPrimes(int limit) {
    // 에라토스테네스의 체 알고리즘 사용
    boolean[] isPrime = new boolean[limit + 1];
    Arrays.fill(isPrime, true);
    isPrime[0] = isPrime[1] = false;
    for (int i = 2; i * i <= limit; i++) {
        // 소수가 아닌 배수들을 걸러냄
        if (isPrime[i]) {
            for (int j = i * i; j <= limit; j += i) {
                isPrime[j] = false;
            }
        }
    }
    List&lt;Integer&gt; primes = new ArrayList<>();
    for (int i = 2; i <= limit; i++) {
        // 소수만 결과 목록에 추가
        if (isPrime[i]) {
            primes.add(i);
        }
    }
    return primes;
}

반대 의견에도 코드 주석이 필요한 이유

코드 주석의 편의성에도 불구하고 이를 부정적으로 보는 시각도 있습니다. 어떤 사람은 ‘코드가 완벽하게 작성되면, 목적과 기능을 분명히 전달할 수 있기에 주석이 필요하지 않다’고 주장합니다. 이런 시각에는 ‘주석을 다는 건 코드에 문제가 있기 때문”이라는 인식이 깔려 있습니다. 이에 주석이 필요 없을 만큼 코드를 완성도 높게 작성해야 한다’는 것이죠.

프로그래밍 언어 Tcl(Tool Command Language)을 만든 존 오스터하우트는 이런 시각을 비판적으로 봅니다. 주석은 부실하거나 불명확한 코드를 덮는 데 사용할 수 있습니다. 그러나 코드만으로 코드 결정의 맥락을 비롯해 다양한 정보를 전달하려면 한계가 있습니다. 주석은 자연어로 쓰기에 코드로 표현할 수 없는 정보도 담을 수 있습니다. 코드 맥락을 파악하고, 코드를 정확히 이해하는 데 주석이 필요한 이유입니다.

어떻게 좋은 코드 주석을 작성하나요?

코드 주석을 무작정 쓴다고 코드를 이해하는 데 도움이 되는 건 아닙니다. 독자를 고려하지 않고 막무가내로 주석을 작성하면 보는 사람에게 유용한 주석을 제공하지 못할 수 있습니다. 좋은 글쓰기 원칙이 있듯 ‘좋은 코드 주석 쓰기 원칙’도 있습니다. 아울러 요즘은 코드 주석을 잘 작성하도록 돕는 자동화 도구도 있는데요. 이는 코드 주석을 쓸 줄 모르는 사람도 올바른 코드 주석을 손쉽게 작성하는 데 도움이 됩니다. 이 글에서는 좋은 코드 주석을 쓰는 4가지 방법을 살펴보겠습니다.

1. 간결하게 작성하기

무분별하게 코드 주석을 작성하지 않고, 꼭 필요할 때만 필수 정보를 포함하여 주석을 씁니다. 또한, 주석에 혼란과 모호함을 줄이고 유용한 맥락과 정보를 제공합니다. 아래와 같은 상황일 때 주석을 작성하면 효과적입니다.

불가피하게 코드가 복잡할 때
정밀도를 높이기 위해 세부 사항을 추가할 때
맥락이 누락됐을 때(예: 다른 리포지터리 또는 패키지의 코드를 사용할 때)

2. TODOs/FIXMEs 주석 사용하기

TODOs/FIXMEs 주석은 ‘코드의 특정 부분에 작업이 완료되지 않았거나 수정이 필요함’을 나타내는 방법으로, 개발자들이 코드에 일반적으로 사용하는 주석입니다. 이는 함수 앞에 “TODO: XX기능을 추가해야 합니다”라는 식으로 작성합니다. 코드를 작성하다 보면 "이 부분은 나중에 다시 살펴보아야겠다" 또는 "이 기능은 추후에 개발해야 한다"와 같은 생각이 들 때가 많습니다. 이럴 때 TODOs/FIXMEs 주석을 사용하면 관련 사항을 기록하고 추적할 수 있습니다. 이는 나중에 코드를 보완할 때 도움이 됩니다.

한편, TODO Highlight 같이 IDE의 별도 확장을 이용하면 주석을 더 편리하게 달 수 있습니다.

TODO Highlight로 주석을 단 모습. 출처=Visual Studio Code

3. 주석으로 코드를 변명하지 않기

잘못되고 불분명한 코드에 주석을 달며 변명하기보다 코드를 새로 작성하는 걸 권장합니다. 모든 코드에 주석을 다는 게 능사는 아닙니다. 어떤 코드는 주석으로 설명해야 하지만, 어떤 코드는 주석에 기대지 않고 ‘코드 그 자체’로 말해야 합니다. 『프로그래밍 스타일 요소』에서는 “잘못된 코드에 주석을 달지 말고 코드를 다시 작성하라”고 조언합니다. 불분명한 코드를 주석으로 해결하려는 건 근본적 해결책이 아닙니다. 코드는 그 자체로 완결성이 있어야 합니다.

1) 문제를 그대로 둔 채 주석을 단 코드

아래 코드는 불분명한 변수명을 그대로 두고, 주석으로 코드를 변명한 예입니다.

python

private static Node getBestChildNode(Node node) {
    Node n; // best child node candidate
    for (Node node: node.getChildren()) {
        // update n if the current state is better
        if (n == null || utility(node) > utility(n)) {
            n = node;
        }
    }
    return n;
}

2) 문제를 해결하고 주석을 달지 않은 코드

아래 코드는 주석으로 코드를 설명하지 않고, 불분명한 코드를 수정한 예입니다. 이 코드는 위 코드의 변수명을 직관적으로 변경했습니다. 따라서 주석 없이 코드 자체만으로 쉽게 이해할 수 있습니다.

python

private static Node getBestChildNode(Node node) {
    Node bestNode;
    for (Node currentNode: node.getChildren()) {
        if (bestNode == null || utility(currentNode) > utility(bestNode)) {
            bestNode = currentNode;
        }
    }
    return bestNode;
}

4. AI 이용하기

인공지능(AI)을 이용하면 코드 주석을 작성하는 시간을 줄이고, 효과적으로 주석을 생성할 수 있습니다. 특히 AI 주석 생성기를 사용하면 특정 표준에 따라 일관된 형식으로 주석을 만들 수 있습니다. 이에 따라 전체 프로젝트에서 주석의 일관성을 유지할 수 있어 코드의 가독성이 향상됩니다.

AI 주석 생성기는 코드 구조와 패턴을 인식할 수 있습니다. 그러나 개발자 의도나 복잡한 로직의 맥락까지 자동으로 생성할 수 없습니다. 이에 주석이 자칫 부정확하게 나올 수도 있습니다. 따라서 자동 생성된 주석만 의존하는 건 위험하며 분별력 있게 사용해야 합니다.