개발 과정에서 문서의 유효성 유지

프로젝트 개발 과정에서 문서화는 다른 설명을 하지 않아도 개발자라면 누구나 인정할 정도로 매우 중요하다. UML을 비롯한 많은 모델링 언어들과 doxygen이나 javadoc 같은 자동 문서화 툴들이 있어 개발자의 문서화 작업을 도와준다. 문서화에 이용되는 많은 편하고 좋은 툴들이 있고 문서화의 중요성을 인정하지 않는 개발자가 거의 없음에도 대부분의 개발자들은 문서화 작업을 좋아하지 않는다. 그 이유에는 여러 가지가 있겠지만 나는 가장 큰 이유를 문서화 작업은 프로그래밍 작업이 다 끝난 다음에 몰아서 하기 때문이라고 본다. 보통 프로그래밍 작업이 끝나면 할일이 다 끝났다는 생각이 드는데 아직도 문서화라는 작업을 해야 하니 일에 의욕이 생기지 않는 것이다. 해결 방안이라면 아직 의욕이 남아있는 프로그래밍 과정 중간에 수시로 문서화를 하게하는 방법이 있을 것이다.

프로그램의 설계 작업 역시 중요한 문서화 작업이다. 물론 최초 문서화 작업 없이 머릿속에 작성해야 할 프로그램의 구조를 떠올리고 한 번에 코딩해 내는 천재들도 있다. 하지만 최소한 나는 그런 천재가 아니다. 오히려 머리가 아주 나쁜 편이기 때문에 열 몇 줄의 코드를 작성하더라도 그 전에 최소한 순서도 정도는 그리고 나야 제대로 된 프로그램을 작성할 수 있다. 그리고 그 보다 더 큰 규모의 프로그램을 작성해야 한다면 함수 관계도 혹은 UML로 클래스 다이어그램 정도는 그려놔야 안정적인 프로그래밍 작업을 할 수 있다. 여기 까지는 별 문제 없다. 오히려 모범적이라고 해야 할까나?

문제는 그 이후에 생긴다. 언제나 말하듯이 나는 천재가 아니다. 그러기 때문에 내가 최초 설계한 프로그램의 로직 구조는 100%의 확률로 수정되어야 한다. 물론 클래스 관계도 역시 언제나 수정된다. 그 수정 사항이 작은 범위에서 적은 빈도로 발생한다면 별 문제는 없을 것이다. 하지만 어떤 경우에는 너무 자주 그리고 매우 광범위하게 생기기도 한다. 또한 그런 경우에는 언제나 디버깅 혹은 테스트에 온 신경이 쏠려 있다. 그것도 아주 날카롭게. 그래서 상대적으로 덜 중요한(!) 설계 문서의 수정 따위는 뒷전으로 밀린다. '일단 코딩부터 마무리 하고 수정하자. 지금 수정하면 수정한지 얼마 지나지도 않아 또 수정한다.'라는 생각이 머릿속을 지배한다. 그 순간부터 내가 최초에 설계했던 문서는 실제 프로그램 소스코드와 일치하지 않게 된다. 문서의 유효성을 상실하게 되는 것이다.

위와 같은 일이 하루에 한 번 정도만 생긴다면 문서는 힘겹게라도 유효성을 유지(소스 코드의 내용과 일치)할 것이다. 하지만 실제 저런 일은 하루에 한 번만 일어나주지 않는다. 현실 세계는 우리가 기대하는 것만큼 아름답지 못하다. 하루에 몇 번씩 전체 소스 코드 여기저기에 수정이 가해지고 나면 이제는 문서를 수정하려고 해도 수정할 내용이 너무 많아져서 점점 문서를 수정하는데 아까운 시간을 점점 많이 투입하게 된다. 하루에 사용할 수 있는 시간은 한정되어 있고 개발자는 그 시간을 최대한 프로그래밍과 테스트에 사용하고 싶어 한다. 당장 눈에 보이는 결과에 영향을 미치지 않는 문서화는 최대한 짧게 끝내고 싶다. '에이 이렇게 된 김에 문서화는 나중에 몰아서 하지 뭐!'

프로그래밍 작업이 어느 정도 마무리 되어서 이제 윗분들(!!!)에게 개발 내용을 보고해야 하는 시점이 다가왔다. 윗분들은 소스코드를 보지 않는다. 결과와 문서를 볼 뿐이다. 문서화는 누가 하는가? 전문 테크니컬 라이터? 아니다. 개발자가 한다. 왜 개발자가 설계도 하고 프로그래밍도 하고 문서화도 해야 하는지는 잘 모르겠지만 아무튼 개발자에게 하라고 시킨다. 해야 한다. 개발자는 자기 할일이 다 끝난 것 같은데 문서화라는 작업을 또 해야 한다. 하기 싫다. 하지만 이미 이렇게 될 줄은 프로젝트를 시작 할 때부터 알고 있었다. 개발자는 문서화 작업을 하면서 생각한다. '이럴 줄 알았으면 코딩하면서 중간 중간 문서 만들껄.'

이야기는 반복된다. 이 악마스러운 뫼비우스의 띠 같은 연쇄에서 벗어나는 방법은 개발자들 누구나 다 잘 알고 있다. 실천하지 못할 뿐이다. 물론 이런 글을 두드리고 있는 나도 전혀 실천하지 못하고 있다.

나는 코딩할 때 코드에 주석을 많이 다는 편이다. 그리고 나중을 생각해 이왕이면 doxygen스타일로 주석을 달고 주석을 달 때마다 그때그때 doxygen을 돌려 제대로 문서가 생성되는지 확인하며 프로그래밍을 하는 것이 거의 습관화 되어 있다. 하지만 그것도 최초 코드를 작성할 때나 유효하지 이미 다 작성된 코드를 조금씩 수정하다 보면 그 수정한 코드를 설명한 주석까지 같이 수정하는 것을 잊게 된다. 결국 그런 작업이 누적되고 시간이 지나고 나면 달려 있는 주석과 그 밑에 있는 소스코드가 서로 다른 내용을 표현하고 있는 경우가 생긴다. 시간이 삼 개월쯤 지난 다음 그런 소스를 보고 있으면 나도 모르게 중얼 거린다.

"나 프로그래밍 더럽게 못하는 구나..."

주석을 포함한 설계 문서, 결과 문서가 실제 구현된 소스 코드와 그 내용이 일치하며 지속적으로 유효성을 유지하게 하는 것. 지금처럼 개발자가 이것저것 혼자서 다 해야 하는 상황에서는 정말 요원한 일이 아닐까?