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