프로그래밍과 주석, 그리고 문서화하기

내가 프로그래밍을 처음 시작했을 무렵 디자인패턴이나 TDD, 개발방법론 같은 것이 있는지도 모르고 있던 시절 항상 날 괴롭혔고 그렇기에 가장 큰 관심사가 되었던 것은 문서화와 주석이었다.

참 많은 사람들이 이것에 대한 이야기를 했다. 그 이야기의 맥락은 문서화가 잘 되어 있으면 주석따위는 필요없다 라는 의견과 주석이 잘 되어 있으면 문서화를 별도로 할 필요가 없다는 것이었는데 이 이야기의 중심에는 언제나 Doxygen이 있었다. 코드에 달아놓은 주석들이 소스코드와 함께 그대로 문서화가 되어버리는 Doxygen.

문서화라는 것을 정말 싫어하는 개발자 입장에서는 최고의 방법이었고 문서화를 주장했던 많은 사람들에게 완전하지는 않지만 그래도만족시킬 수 있는 수준의 문서화방법이 되어주었기에 Doxygen은 이 논란의 시작이자 마무리가 되어주곤 했다.

시간이 꽤 지난 지금 생각을 해 보면 이 논란은 서로 다른 분야에 있는 이야기를 같은 분야에 있는 것으로 착각하고 진행을 해온게 아닌가 아는 생각이 든다. 문서화와 주석이란 서로 다른 분야에 있는 것인데 그것을 같은 곳에 있는 것이라고 착각을 했던것이 아닐까?

문서화에 대해서 내 스스로 내린 정의는 프로젝트에 대한 백서(White paper)를 만들어내는 과정을 이야기한다고 생각한다.

프로젝트에 대한 공식 보고서중에 프로그래밍 분야에 대한 항목을 만들어내는 것이 문서화가 되며 문서화에서 주력해야 하는 것은알고리즘, 구현(릴리즈)목표와 일정, 세부 진행사항, (큰 의미에서의) 클래스 설계에 관련된 내용이 포함되어 있어야 한다.
문서화의 목적은 어떤 프로그래머든간에 문서화 자료를 봤을 때 프로젝트의 숲 전체를 바라보며 그 숲이 어떻게 구성되어 있는지를 알게 하는 것이 목표가 되어야 한다.

그렇다면 주석은 뭘까?
주석은 레퍼런스를 만드는 과정이다. 그리고 Doxygen은 효율적인 레퍼런스를 만들어주는 툴이 되어줄 수 있다. 즉, 이 곳에는 어떤 나무들이 심어져있는지를 보여주는 것이 목표가 되어야 한다.
실제로 Doxygen으로 생성된 문서를 봤을 때 그것을 통해 프로젝트를 이해하는 것은 굉장히 어렵다. 하지만 내가 찾고자 하는 부분을 찾아 들어갈 때는 그 어떤 것 보다도 힘이 되어준다.

문제가 발생했을 때 해당 문제가 생기는 원인을 문서화 작업으로 만들어낸 백서에서 찾아내고 찾은 부분에 대한 구체적인 확인은레퍼런스에서 하며 그 확인이 끝났을 때 코드에 수정하는 "문서화자료 --> 주석(레퍼런스) --> 코드"의 과정이이루어지도록 해야 한다.

그러므로 프로그래머라면 문서화도 주석도 소홀히 해선 안된다고 생각한다.
결국 프로그래머는 코딩, 알고리즘과 더불어 주석, 문서화까지 신경써야 한다는 깝깝한 이야기가 되어버리긴 했지만 내가 했던프로젝트를 5년쯤 후에 다시 맞닥뜨리게 되었을 때 적어도 내 코드를 보면서 머리 갸웃거리기 보단 당당하게 후임자에게 "내가도와줄 거 별로 없지?"라고 말해줄 수 있는 프로그래머가 되는게 훨씬 멋있지 않겠는가.