한빛출판네트워크

제공 : 한빛 네트워크
저자 : Brian MacDonald
역자 : 권혁이
원문 : The art of commenting

코드에 주석을 다는 것은 시간낭비일까, 아니면 프로그래머에게 있어서 황금과 같을까?

개발자들에게 프로그래밍 관련 작업 중 가장 적은 시간을 투자하는 게 무엇인가 물어본다면 문서화 작업이라는 답변을 듣게 될 것이다. 프로그래머들은 코드를 작성하려고 하지, 어느 누가 지루하게 코드의 문서화 작업을 원하겠는가? 그러나 문서 작성은 개발을 계속 진행되도록 해주는 기름과 같아서 좋은 문서는 직장 동료나 사용자, 심지어 자기 자신에게도 도움이 된다. 문서작성의 가장 기본은 스스로 자신의 프로그램 대한 주석 달기에 있다.

주석은 정말 중요하다

처음 프로그래밍을 배우는 과정에서 디버깅이 가능한 단순한 프로그램을 만들 때에는 주석이 불필요하다. 해당 코드가 무슨 동작을 하는지는 코드를 보면서 이해할 수 있기 때문이다. 반면, 코드가 복잡해지기 시작하면 주석에 의존할 수밖에 없게 된다. 코드 작업에서 벗어나 일주일이나 하루, 심지어 몇 시간이 지나면, 작업할 당시에는 명확하고 뚜렷하다고 생각했던 코드도 머릿속에서 지워져서 완벽하게 이해할 수 없게 된다. 다른 사람이 작성한 코드로 작업이 필요한 상황에서는 더 심각하다. 무슨 생각으로 해당 프로그래머가 코드를 작성했는지 이해하지 못할 때는, 주석이 그 프로그래머의 생각을 판단할 수 있는 필수요소가 된다.

거의 모든 프로그래밍 언어는 주석을 다는데 몇 가지 양식을 갖고 있으며(만약 그렇지 않은 언어를 알고 있다면 댓글로 알려달라) 식별하기가 꽤 쉬운 편이다. 대부분의 언어는 주석을 빠르게 기입하기 위해 인라인 주석과 자세한 정보를 담기 위한 블록 단위의 긴 주석을 모두 제공한다. 주석의 올바른 문법은 언어에 따라 다르나 구문 강조(신텍스 하이라이트)가 지원되는 IDE를 사용하면 대게 코드와 다른 색상으로 주석 식별이 가능하다. 일반적으로 주석은 특수 문자를 접두사로 사용한다. 예를 들어 C++이나 자바에서 인라인 주석은 다음과 같다.

// 주석을 사용한다. 컴파일러는 해당 라인의 끝까지 전부 무시하게 된다.

자바를 포함한 몇몇 언어에서는 주석을 코드에서 분리하여 문서화되는 도구를 제공한다. 주석의 품질을 높여주게 되는 것이다.

주석 작성에 필요한 것은?

당연한 말이지만, 자신의 코드와 관련된 모든걸 설명하면 코드보다 주석이 더 많아질 수 있다. 그렇다면 주석을 작성할 때 필요한 것은 무엇이 있을까? 주석의 작성은 어느 정도 코드를 작성함에 있어서의 경험에 의존적이다. 예를 들어 이제 막 프로그래밍을 시작한 단계라면 다음과 같은 주석을 남기곤 한다.

int numStudents = 6;  // numStudents에 6의 값을 할당한다.

이 주석은 그다지 유용한 내용이 아니며, 코드가 무엇을 하는지 주석을 통해 다시 반복해서 말할 뿐이다. 초보자라면 도움이 될 수도 있지만, 조금의 경험이 있는 프로그래머라면 이와 같은 주석이 불필요하다. 코드를 작성할 때 가장 큰 실수는 이 코드가 무엇인지, 아니면 왜 이렇게 작성했는지 보다는 해당 코드가 어떻게 동작하는지 주석으로 설명하는데 있다. 예를 들어 다음과 같이 변수에 특정 값을 할당할 때를 생각할 수 있다.

int numStudents = CountStudents();  // CountStudents 함수는 학생 정보 데이터를 순환하여
                                    // 현재 해당 수업에 등록된 학생수를 반환한다.

이와 같은 주석이 전보다 더 유용하다. 해당 함수를 통해 현재 학생 수를 구하게 되는데, 이렇게 주석을 달아놓고 해당 코드를 보는 사람들에게 무엇을 하는 함수인지 정확하게 말해줄 필요가 있다. 그래서 이 함수는 해당 학교의 모든 학생수가 아닌 등록된 학생수만 반환한다는 걸 알 수 있다. 만약 해당 함수가 학생수를 얻어오려고 데이터베이스에 접근해야 한다면, 주석에다가 해당 데이터베이스에 대한 몇 가지 정보를 포함시킬 수도 있다. 또한, 다음과 같이 해당 함수에 관한 적절한 주석을 포함시킨다.

int CountStudents(Student students[], int courseNumber);
/* Student 객체의 배열과 코스 번호를 가져온다.
* courceNumber의 코스번호로 등록된 학생 수를 반환한다.
* courseNumber가 유효한 값이 아니면 예외를 던진다.
*/
{...}

이 주석을 통해 코드를 직접 훑어볼 필요 없이 해당 함수에 대해서 알 수 있다. 함수의 입력인자 의미와 예상되는 반환값에 대해서도 알 수 있다. 또한, 해당 코드에서 잘못된 코스 번호가 입력되면 예외(에러)가 발생할 수 있다는 사실도 알 수 있다. 주석만으로는 어떠한 방식으로 코스 번호를 판단하는지 알려주지는 않는다. 이점은 해당 함수를 사용함에 있어서 문제가 되지 않는다. 대부분의 개발자들은 이런 정보가 포함된 주석이 달린 함수를 선호한다. 작업하는 곳과 어떤 주석을 어떻게 달지에 따라 정책상의 문제가 될 수도 있다. 많은 개발자와 프로젝트를 진행한다면, 모두를 위해 시간과 불만을 줄일 수 있도록 주석에 대한 일관된 포맷을 가져라.

또 다른 방법은 없나?

늘 그렇듯 프로그래밍 기본 원칙에 관한 의견에는 반박이 있기 마련이다. Visual Studio Magazine에 올라온 글을 보면 "읽기 쉬운 코드" 연습방법으로 깔끔하고 명확한 변수 이름과 함수 이름을 사용으로 문서화는 필요 없다고 말한다. 코드 자체가 문서이기 때문이다. 꽤 훌륭한 생각이다. 그렇지만 읽기 쉬운 코드로 작성한 다음 조금 더 알기 쉽게 주석을 포함해서 나쁠 건 없다. 주석을 사용하게 되면 아무리 숙련된 개발자라도 코드를 통해서 읽는 것보다 해당 프로그래머의 의도를 파악하기가 쉽다. 프로그래머에게 있어서 코드에 쏟아 붓을 시간을 주석 작성으로 낭비하게 된다고도 할 수도 있다. 테크니컬 에디터라서 그런 것도 있지만, 다른 사람들이 당신의 코드를 이해할 수 있도록 시간을 들이는 것은 내가 봤을 때 시간을 잘 쓰는 것처럼 보여진다.