ZDNET에 올라온 나쁜 프로그래머가 되는 18가지 방법을 보면서 느낀 점을 몇 가지 적어봅니다. 이 글은 무려 18가지 방법에 대해 이야기하고 있는데, 일단 코드 주석에 대한 부분만 제 의견을 적어볼까 합니다.

9. 소스코드가 주석 하나 없이 깨끗하다

항상 주석 같이 읽기 쉬운 소스코드를 주장하면 주석 하나 없이 깨끗하게 코딩을 한다. 하지만 후배들은 주석이 없으면 이해하기 어렵다고 불평이다. 하지만 프로젝트 일정이 항상 너무 촉박해서 소스코드에 주석을 적을 시간이 없다.

보통 이런 상황은 주석이 없어서 코드가 이해하기 힘든 것이 아니라 코드가 이해하기 힘드니깐 주석이라도 달아서 설명을 해달라는 뜻입니다. 이런 불평이 나오면 주석을 쓸 게 아니라 코드를 리팩토링하거나 제대로 작성해야 하는 게 먼저입니다.

프로그래밍을 하다 주석이 필요하다고 느끼면 주석을 적기 전에 2번, 3번 다시 생각을 해야 합니다. 정말 주석을 달아야만 이해할 수 있는 코드인지, 주석이 아니라 코드에 작성자의 의도를 표현할 수 없는지 등을 고민하다 보면 대게의 경우 코드를 좀 더 잘 작성할 수 있는 방법을 찾게 됩니다.

주석은 코드가 아니기 때문에 시간이 지나면 코드와 주석이 따로 노는 현상이 빈번히 발생합니다. 변경이 잦은 코드일수록 주석은 빠르게 쓸모 없어지고, 코드를 읽을 때 오히려 혼란만 초라하게 되는 경우가 더 많습니다. 위 글 필자의 말처럼 프로젝트 일정이 항상 촉박하고 바쁜데, 코드뿐만 아니라 주석까지 유지보수할 개발자는 흔치 않기 때문입니다.

좋은 코드를 짜는 것도 어렵지만 좋은 주석을 다는 건 더 어렵습니다. 저는 코드 리뷰하면서 좋은 주석을 본 적이 거의 없습니다. 코드를 왜 이렇게 이상하게 짤 수밖에 없었는지 변명하거나, 코드에 이미 다 나와 있는 내용을 중복으로 기술하는 주석이 대부분입니다. 사실 이 정도도 글을 잘 쓰는 개발자나 할 수 있고, 대부분의 개발자는 함수 이름을 그대로 반복하는 수준의 주석만 씁니다. 예를 들어 함수 이름이 readFile이면 주석에 “파일을 읽는다”라고 쓰는 거죠. 그래서 저는 주석 쓸 시간에 코드를 좀 더 읽기 쉽게 짜라고 조언합니다.

물론 주석과 문서화는 다른 이야기입니다. 비전 문서, 아키텍처 문서, 설계 문서, API 문서 등 명확히 목적과 이유가 있는 문서들이 존재합니다. 하지만 우리가 흔히 “코멘트”라고 이야기하는 코드 주석은 명확한 목적성을 갖는 문서가 아니라 잘못을 변명 혹은 반성하는 경위서에 가깝습니다.

추가로 서두에 인용한 글처럼 소프트웨어 엔지니어링, 개발 프로세스 등에 대한 글을 쓸 때 “코드에 주석이 없으면 나쁜 개발자가 된다”는 식으로 결론만 이야기하는 건 무의미하다고 생각합니다. 이런 종류의 문제는 원래 정답이 없고 환경과 상황에 따라 적당한 수준을 찾는 과정이기 때문입니다.

코드 주석에 대해서 결론은 이미 정해져 있습니다. 필요한 만큼 적당한 수준으로 잘 적어야 잘하는 거죠. 이런 주제의 글을 쓰려면 여러 사례나, 본인의 경험담 등을 통해 그 뻔한 결론에 도달하는 과정을 보여줘야 합니다. 단순히 주석이 없으면 나쁘다는 글을 읽고 개발자들이 무엇을 배울 수 있는지 모르겠습니다.