[개발자의 서재] "실용주의 프로그래머" 44. 결국은 모두 글쓰기

문서는 필요악? 코드 ≒ 문서

많은 수의 개발자들이 문서 작성을 불필요한 작업이라고 생각한다. 고작해야 필요악 정도로 인식하는 경우가 많다. 프로젝트가 끝날 무렵에나 어쩔 수 없이 문서를 작성하기 시작한다.

하지만 실용주의 프로그래머들은 문서화를 필수 불가결한 요소라고 생각한다. 다른 점은 노력을 중복하거나 시간을 낭비하지 않고, 문서를 늘 코드와 가깝게 두면서 항상 문서를 촉촉하게 유지한다. 이런 방법들이 완전히 새로운 것은 아니고 JavaDoc, pydoc 등 다양한 부분에서 이미 이뤄지고 있다.

이제부터 소프트웨어의 내부, 외부 문서들을 어떻게 관리해야 하는지 다뤄보겠다.

• 문서화의 필요성은 알고 있지만 실천하지 못했다. 최근에 와서는 그 필요성을 뼈저리게 느끼고 있다.
• 나중으로 미루지 말고, 처음부터 제품에 녹여야 한다. 그렇지 않으면 곱절 이상의 비용이 발생한다.

내부 문서(주석, 코드)

소프트웨어의 내부 문서인 주석은 공학적인 트레이드오프나 어떤 결정의 이유, 어떤 대안을 버렸는지 등 다른 곳에서 문서화할 수 없거나 추적되기 어려운 내용들을 기록해야 한다. 코드가 어떤 행위를 하는지 주석을 다는 것은 DRY 원칙 위반이다.

변수, 함수, 클래스 이름은 유의미하고 정확하게 지어야 한다. foo, doit, manager 처럼 의미를 알 수 없거나 포괄적인 이름은 코드를 읽는 개발자에게 필요한 정보를 전달하지 못한다. 하지만 부정확한 이름으로 오해를 불러일으키는 경우는 더욱 심각하다. getData라고 이름 지었지만 실제로는 데이터를 생성하여 알 수 없는 사이드 이펙트 때문에 고생한 경험이 있는가?

• 7. 중복의 해악에도 나온 내용이다. 코드도 문서도 결국은 의미를 가진 문자열의 집합으로 독자한테 읽혀져야 할 운명이다.

외부 문서(사용자 메뉴얼)

데이터 스키마나 API를 관리하는 것은 중복적인 작업을 요구한다. 구조나 기능이 변경될 때마다 같이 문서를 수정해줘야 하지만 사람이 작업하는 것이다 보니 누락되는 경우가 종종 생기게 된다. 이를 방지하기 위해서 코드로부터 문서를 생성하는 방법을 권장한다. 코드에 작성된 주석, sql 등을 파싱하여 문서를 생성하는 것이다.

문서가 최종적인 소스가 되게 하지 말고 다른 것을 사용하도록 하고, 형태를 자유롭게 바꿀 수 있도록 해라. 만약 마크업 시스템을 사용하고 있다면 문서, 슬라이드 등 다양한 포맷을 지원할 수 있다.

• 이 부분 역시 7. 중복의 해악에 나온 내용이다. 늘 그렇지만 자동화만큼 유지보수 비용을 낮춰주는 것은 없다.

책임

간혹 테크니컬 라이터가 있는 조직에서는 문서 작업의 책임을 테크니컬 라이터들에게 떠넘기곤 한다. 이것은 실수다. 프로그래머들이 문서를 작성하지 않는다는 것이 지금까지 다뤘던 실용주의 원칙을 저버려도 된다는 뜻은 아니다. 우리는 글을 쓰는 이가 실용주의 원칙을 포용하기를 원한다. 끝까지 책임감을 가지고 문서 관리에 힘써야 한다.