[번역] Code Tells You How, Comments Tell You Why

Code Tells You How, Comments Tell You Why

18 Dec 2006

"코드 주석에 대한 철학"이라는 이전 포스트에서 말했듯이, 최고의 코드 주석이란 사용할 필요가 없는 코드 주석(이하 주석)이다.. 다시 한번 강조해서 말하자면, 주석 없이도 이해가 가능한 간단한 코드를 작성하도록 노력해야 한다. 코드로는 쉽게 이해하기 어려운 곳에만 주석을 추가하도록 한다.

이렇게 함으로써 청중을 의식하고 코드를 작성할 수 있다. 1985년에 발간된 고전인 "Structure and Interpretation of Computer Programs"의 서문에서도 이를 올바르게 지적하고 있다.

프로그램은 사람들이 읽을 수 있도록 작성되어야 하며, 단지 부수적으로 기계가 실행할 수 있어야 한다.

Knuth는 그의 1984년 고전적 에세이인 LiterateProgramming(pdf)에서 유사한 의견을 다루고 있다.

프로그램 작성에 대한 우리의 전통적인 태도를 바꾸어 보자 : 우리의 주된 목표가 컴퓨터가 무엇을 할 것인지를 지시하는 것이 아니라, 컴퓨터가 어떻게 동작하기를 원하는지를 인간에게 설명하는 것에 집중해 보자.

"literate programming"를 실천하는 사람은 수필가라고 할 수 있는데, 그들의 주된 관심사는 상세한 설명과 문체의 탁월함이다. 이런 저자는 유의어 사전을 항상 손에 쥐고, 매우 신중하게 변수의 의미를 설명할 수 있는 변수명을 고른다. 저자는 서로를 보강하는 공식적이고 비공식적 방법을 섞어 가면서, 인간이 이해하기 가장 좋은 순서로 개념을 소개함으로써 알기 쉬운 프로그램을 작성하기 위해서 노력한다.

당신 코드의 첫번째 소비자는 다른 프로그래머이고, 컴파일러는 그 다음이라고 생각하고 코드를 작성한다면, 부가적인 코드 주석의 필요성은 크게 줄어들 것이다. "using comments as a crutch"는 매우 훌륭한 설명이다.

이것은 몇년간 양산에 적용된 자금이 풍부한, 폐쇠형 source 시스템에서 가져온 코드의 snippet이다.

float _x = abs(x - deviceInfo->position.x) / scale;

int directionCode;
if (0 < _x & x != deviceInfo->position.x) {
    if (0 > x - deviceInfo->position.x) {
        directionCode = 0x04 /*left*/;
    } else if (0 < x - deviceInfo->position.x) {
        directionCode = 0x02 /*right*/;
    }
}

아래 코드는 위와 동일하지만, 버그를 수정하고 보다 읽기 쉽게 바꾼 것이다.

static const int DIRECTIONCODE_RIGHT = 0x02;
static const int DIRECTIONCODE_LEFT = 0x04;
static const int DIRECTIONCODE_NONE = 0x00;

int oldX = deviceInfo->position.x;
int directionCode = (x > oldX)? DIRECTIONCODE_RIGHT
                  : (x < oldX)? DIRECTIONCODE_LEFT
                  : DIRECTIONCODE_NONE;

주석이 많다고 더 읽기 쉬운 코드는 아니다. 위 예에서는 그렇지 않았다. 위 코드에서의 주석은 - 당신이 이미 알아차렸더라도 - 코드를 보다 복잡하게 할 뿐이다. 때로는 적은 주석이 보다 읽기 쉬운 코드를 만든다. 특히 주석 대신 의미 있는 심볼명을 사용한다면 말이다.

주석을 사용하지 않도록 개정하고 단순화할 수 있는 거의 무한한 기회가 있지만, 주석 없이 코드만으로 설명하는데는 한계가 있다.

코드가 아무리 간단하고, 간결하고, 명확하더라도, 코드가 완전히 스스로 문서를 대체할 수는 없다. 코드만으로 주석을 대체할 수는 없다. Jef Raskin의 말을 들어보자.

코드는 프로그램이 왜 작성되었는지, 이 방법 혹은 저 방법을 선택한 논리적 이유는 무엇인지는 설명할 수 없다. 코드는 여러 가지 대안 중에서 특정 방법이 선택된 이유를 설명할 수 없다. 예를 들면,

/* A binary search turned out to be slower than the Boyer-Moore algorithm for the data sets of interest, thus we have used the more complex, but faster method even though this problem does not at first seem amenable to a string search technique. */

어떤 개발자에게는 완벽하게 명백한 것이라도, 맥락을 모르는 다른 개발자에게는 전혀 이해하기 어려울 수 있다. 다음과 같은 주석에 대한 조언을 생각해 보자.

아마 아래와 같은 코드는 쉽게 잘 알것이다.

$string = join('',reverse(split('',$string)));

문장을 역전시키는 것. 하지만 아래와 같은 문구(주석)를 Perl에 넣는 것이 어려울까?

# Reverse the string

사실 전혀 어렵지 않다. 코드는 어떻게(How) 프로그램 동작하는지를 설명하고, 주석은 왜(Why) 동작하는지를 설명하도록 하면 된다. 이를 헷갈리지 않으면 된다.

Written by Jeff Atwood

Indoor enthusiast. Co-founder of Stack Overflow and Discourse. Disclaimer: I have no idea what I'm talking about. Find me here: http://twitter.com/codinghorror

---

원본 링크 : https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/

* 다소 의역한 부분도 있으므로 정확하지 않을 수 있습니다. 원본 번역에 문제를 알려 주시면 내리도록 하겠습니다.