컴퓨터 프로그램은 인간이 기계에게 보내는 메세지인 한편, 인간 사용자에게 자기 이야기를 들려주는 또 다른 측면
이 있다.
가장 사적인 프로그램이라도 저자이자 사용자인 사람의 기억은 시간에 따라 희미해지고, 자기가 만든 작품이지만 세부적인 내용은 기억을 되살려야 한다. 저자와 사용자가 시공간적으로 떨어져 있는 공개 프로그램 에서 문서화
는 특히 더 중요하다.
프로그램 문서화를 어느 수준으로 할 지는 프로그램을 사용하는 사용자의 목적과 환경
에 따라 달라진다.
모든 사용자에게는 프로그램에 대한 상세한 설명이 필요하지만, 사용자에게 유의미한 상세설명을 작성하기 위해선 뒤로 한발 물러나 전체적인 개관
을 제시하는데 주안을 두어야 한다.
프로그램이 어떻게 사용되고, 또 어떻게 제대로 동작하는지 알기 위해선 테스트 케이스
가 필요하다. 출하된 모든 프로그램 사본에는 소규모 테스트 케이스가 포함되어서, 해당 사본이 신뢰할 수 있고 정확히 동작함을 일상적으로 재확인 할 수 있어야 한다.
프로그램을 개작하거나 고치기 위해선 세부 내용 전체가 필요하며, 적절하게 주석이 달린 리스팅 안에 담겨져야 한다. 일반적인 사용자는 물론 수정하는 사람에게도 명확하고 뚜렷한 개관은 절실히 필요 하지만, 이번에는 내부구조
에 대한 것도 필요하다.
순서도는 프로그램 문서화 중에서도 가장 과대 선전된 기법이다. 대개는 순서도 자체가 전혀 필요하지 않고, 한 페이지를 넘는 순서도가 필요한 경우는 드물다.
순서도가 한쪽에 들어갈 수 있다면 판단 구조가 그나마 우아하게 나타나며 상당히 유용한 반면, 여러 쪽에 걸쳐 덕지덕지 이어진 경우에는 전체 모습을 파악하기가 쉽지 않다.
데이터 처리의 기본 원칙에서는 같은 키값에 대응하는 모든 정보를 각 파일로부터 모아서 한 레코드에 담고 하나의 파일로 두는 것이 훨씬 낫다.
위와 같은 논리로 컴퓨터가 실행하는데 필요한 문서(소스코드)와 사용자에게 상세한 설명을 하기 위한 문서(매뉴얼)을 분리하는 것보다 합쳐서 문서 내용이 프로그램 소스에 포함되게 할 수 있다. 이것을 자체 문서화 프로그램
이라 칭한다.
요즈음에는 너무나 당연하게 이뤄지고 있는 방식인데 과거에는 참신한 방식이었던 것 같다. 오히려 이 방식이 지금까지 내려와서 필자에게 전승된 것일 수도 있다.
일단 한번 쭉 옮겨 적었지만 요즈음 프로그래밍 언어와 개발 환경에 비추어 봤을 때, 물론 주석의 중요성은 이루 말할 수 없으나, 위는 너무 과도하다는 생각이 든다.
오히려 주석이 없어도 쉽게 이해할 수 있는
간명한 코드
가 더 좋다는 것이 필자의 생각이다.리눅스 커널의 코딩 스타일 문서
만 봐도 이에 대한 깊은 철학을 엿볼 수 있다.
가장 심각한 반대 이유는 저장할 소스코드의 증가
이지만 문서화 프로그램을 합치면 저장할 총 글자수는 줄어든다
.
하지만 자체 문서화라는 접근법은 고급 언어의 사용에서 자극받은 것이니 만큼, 일괄처리를 대화식이든 온라인 시스템에서 고급 언어와 함께 사용될 때 가장 큰 효용과 정당성을 찾을 수 있다.
[책] 맨먼스 미신: 소프트웨어 공학에 관한 에세이 (프레더릭 브룩스 지음, 강중빈 옮김)