모든 개발팀이 문서화 정책을 갖고 있겠죠. 팀마다의 상황이 다르고 개인차도 있겠지만, 이 글에서는 제가 지금까지 경험해 본 문서화에 대한 내용들을 좀 정리해 볼까 합니다.
우선, Doxygen(을 포함한 자동 문서 생성 도구)은 별로 쓸모가 없었습니다. 최근의 IDE들은 프로그래머들에게 다양한 정보를 제공해 줍니다. VC의 IntelliSense는 상당히 잘 동작하고, 그걸로는 부족하다고 생각하는 개발팀들의 경우엔 VisualAssist를 사용합니다. 이런 상황에서 Doxygen이 생성하는 클래스 및 함수 목록은 별반 도움이 안 됩니다. 다만 클래스 계통도를 뽑아두면 한 눈에 전체 구조를 볼 수 있다는 점 정도가 약간 쓸모가 있을 뿐인데, 주석이 없어도 되는 그 정도의 작업을 위해 소스 코드에 Doxygen 형식의 주석을 달아두는건 별로 좋은 방법이 아닌 것 같습니다. 코드가 지저분해 질 뿐이죠.
하지만 최신 IDE에서는 Doxygen 형식으로 함수나 클래스의 요약을 정리한 주석을 약간 달아두면 툴팁으로 확인할 수도 있으니(이것도 꼭 Doxygen 형식일 필요는 없지만;;) 약간 정도는 주석을 달아준다고 칩시다. 이런 경우에는 어디까지 주석을 달아야 할 지가 문제인데, 제가 보기에는 소스코드의 작성자가 필요하다고 생각되는 곳에 필요하다고 생각되는 내용만큼만 달면 됩니다. 다만 최소한의 원칙을 정한다면 brief 태그를 주로 사용하는 걸로 하고 author 태그를 금지해야 합니다. author 태그는 여러 프로그래머가 같이 작업하는 요즘의 게임 개발 프로젝트에서 거의 아무런 쓸모가 없고, 함수를 업데이트 하는 경우에 갱신하기도 애매해서 방치하다 보면 정보를 전혀 제공하지 않는 의미 없는 태그가 됩니다.
지금까지 해본 여러 가지 형식의 문서화 중에 가장 성공적인 경우는 Wiki를 사용했을 때입니다. 모듈 하나를 완성하면 그 모듈의 사용법에 대한 레퍼런스를 작성하는 방식으로 했을 때가 그나마-_- 가장 문서화가 잘 됐던 것 같아요. 문서화에 대한 부담도 상대적으로 적은 편이었구요. 요즘엔 대부분 Trac이나 Mantis등의 버그 트래킹 시스템을 사용하니까, 이에 연동된 Wiki에 문서화를 하는 게 가장 좋은 결과가 나왔습니다.