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

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

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

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

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

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

public static List<Integer> 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<Integer> 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의 별도 확장을 이용하면 주석을 더 편리하게 달 수 있습니다.

photo | 인포그랩 GitLab | 인포그랩 GitLab
TODO Highlight로 주석을 단 모습. 출처=Visual Studio Code

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

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

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

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

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) 문제를 해결하고 주석을 달지 않은 코드

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

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

photo | 인포그랩 GitLab | 인포그랩 GitLab
AI 주석 생성기 ‘Readable’ 작동방식. 출처=Readable

아래는 AI 주석 생성기 Readable로 코드 주석을 작성한 모습입니다.

photo | 인포그랩 GitLab | 인포그랩 GitLab
출처=Readable

맺음말​

코드 주석은 개발자에게 필수 도구로, 코드 이해를 돕고 나중에 코드를 볼 다른 개발자에게 유용한 가이드가 될 수 있습니다. 적절한 주석은 코드 품질을 높이고 팀워크를 강화하는 데 중요한 역할을 합니다.

인포그랩은 GitLab 및 DevOps에 대한 맞춤 기술 지원을 제공합니다. GitLab(Omnibus/Cloud Native Hybrid) 구축 관련한 지원이 필요하시면 문의하기 로 연락 주십시오.

<참고 자료>

  1. Docs for Developers 기술 문서 작성 완벽 가이드
  2. Clean Code
  3. Best practices for writing code comments
  4. The Engineer’s Guide to Writing Meaningful Code Comments
  5. 코드 가독성에 대해 - 2. 명명과 주석