지난번에 [B급 프로그래머] (2) 소프트웨어 설계 "프로세스"가 항상 이상화된 형태인 이유는?을 올려드리며 잠깐 한숨을 돌렸다. 마지막으로 다룰 내용은 3부작의 핵심인 이상화된 설계 문서를 _쉽고 제대로_ '위조'하는 방법이다. 파나스 큰 형님이 쓰신 논문의 'II. FAKING THE IDEAL PROCESS"를 함께 읽어보자. (이하 스크롤 압박 주의!)
앞서 우리가 따르고 싶은 이상적인 프로세스와 이 프로세스를 따르는 동안 만들어야 하는 문서를 설명했습니다. 우리는 마치 이상적인 방식에 따라 뭔가를 작업했다는 듯이 문서를 작성하는 방식으로 이런 프로세스를 "위조"합니다. 앞서 설명한 순서에 따라 문서를 만들어내려 노력합니다. 정보의 일부가 존재하지 않는다면, 이런 사실을 해당 정보가 등장해야 마땅한 문서의 일부로 기술하며 마치 정보가 변경되리라는 사실을 기대하듯 설계를 계속 진행해야 합니다. 오류를 찾으면, 반드시 수정하고 문서에 관련된 변경을 가해야 합니다. 문서는 설계를 담은 매체이며, 문서에 통합되기 전까지는 해당 설계 결정이 내려지지 않은 것처럼 취급해야 합니다. 중간에 얼마나 발이 걸려 넘어졌는지 무관하게, 최종 문서는 이상적이면서 정확해야 합니다. 심지어 우리가 가장 이성적이라 여기는 수학 분야조차도 이런 절차를 따릅니다. 수학자들은 근면성실하게 증명을 다듬어, 처음과는 완전히 다른 증명을 내놓습니다. 첫 증명은 종종 지극히 고통스런 발견 프로세스의 결과입니다. 수학자들이 증명을 해나감에 따라 이해도가 높아지며 단순화할 방법을 찾아냅니다. 궁극적으로, 몇몇 수학자들은 이론의 진실을 좀더 명백하게 밝혀줄 더 단순한 증명을 찾아냅니다. 더 단순한 증명을 논문으로 출간하는 이유는 독자들은 이론의 진실에 관심이 있지, 이론을 찾아나서는 프로세스에 관심이 있지 않기 때문입니다. 소프트웨어에도 이와 유사한 추론을 적용할 수 있습니다. 소프트웨어 문서를 읽기를 원하는 독자들은 프로그램을 이해하기를 원하지, 프로그램 제작 과정을 다시 경험하기를 원하지는 않습니다. 이상적인 문서를 제공하는 방법으로, 실제 독자들이 필요한 내용을 제공할 수 있습니다. 우리가 만든 문서를 이상적인 문서와 비교하면 한 가지 중요한 차이점이 있습니다. 우리에게는 수용하고 거부했던 설계 대안을 모두 기록하는 정책이 있습니다. 각 대안에 대해 왜 수용했으며, 왜 마지막으로 거부했는지를 설명합니다. 여러 달, 여러 주, 심지어 여러 시간이 지난 다음 우리가 무엇을 어떻게 했는지 궁금하게 여길 때, 문서에서 찾을 수 있습니다. 지금부터 여러 해가 흘러, 유지 보수 인력이 동일한 질문에 부딪혔을 때, 대답을 문서에서 찾을 것입니다. 이런 프로세스가 성과를 거두는 실례는 이상적인 프로세스를 보여주는 일부로 몇 년 전에 작성된 소프트웨어 요구 사항 문서를 들 수 있습니다. 일반적으로 요구 사항 문서는 코딩을 시작하기 전에 만들어지며, 결코 다시 사용되지 않습니다. 해당 요구 사항 문서를 만족하는 현재 소프트웨어의 운영 버전은 여전히 변경이 가해지고 있습니다. 소프트웨어를 테스트해야 하는 조직은 테스트를 광범위하게 선택하기 위해 이런 요구 사항 문서를 활용합니다. 새로운 변경이 필요지면 어떤 변경이 가해져야 하며 어떤 변경이 가해지면 안 되는지 기술하는 문서를 참조해야 합니다. 여기서 우리는 이상적인 프로세스의 시작 시점에 만든 (위조된) 문서가 소프트웨어를 실제 환경에 투입하고 나서 여러 해가 지난 다음에도 여전히 사용되고 있음을 볼 수 있습니다. 메시지는 명확합니다. 만일 문서를 주의 깊게 작성한다면 오랜 기간 동안 유용할 것입니다. 그리고 반대로, 이렇게 만든 문서가 광범위하게 쓰인다면, 올바로 작성할 가치도 있을 것입니다.
원문이 한 문단으로 되어 있어 중간에 일부러 끊지 않았으므로, 한 번만 더 읽어보자. 두 번 읽었다면 지금부터는 실제로 이상적인 문서를 '위조'하는 방법에 대해 고민할 차례다. 본문을 읽다보면 밑줄을 그어야 하는 부분이 여러 곳 존재하는 데 그 중에서도 특히 "소프트웨어 문서를 읽기를 원하는 독자들은 프로그램을 이해하기를 원하지, 프로그램 제작 과정을 다시 경험하기를 원하지는 않습니다."라는 부분에 주목할 필요가 있다. 문서를 작성하는 과정에서 부딪히는 가장 큰 어려움은 바로 '우리가 앞으로 실제로 진행해야할 작업을 이상적인 형태가 아니라 전지적 관점에서 시시콜콜 기술하라'라는 말도 안 되는 요구다(말이 안 되는 이유는 시리즈 (1)번을 다시 읽어본다). 이런 말도 안 되는 요구에 따라 만든 문서로 최종 결과물을 검수하려니 여기저기서 삐걱거린다. 요구 사항을 낸 쪽에서는 미리 요구 사항을 제대로 수집하지 않았다고 난리며, 개발한 쪽에서는 애초부터 구현이 불가능한 설계 명세라고 난리다. 최종 사용자는 자신들의 의견이 반영되지 않았다고 난리며, 유지보수하는 인력들은 실제 개발 과정에서 일어난 변경 사항이 하나도 반영 안 된 죽은 문서라고 난리다. 어차피 책장 속에 들어가 다시는 꺼내보지 않을 운명에 처한 문서가 이 난리를 칠만큼 가치 있는지는 정말 잘 모르겠다.
그렇다면 문서를 어떻게 위조해야 할까? 개인적인 경험에 따르면, 미션 크리티컬한 프로젝트가 아니라면(음... 국방, 금융 말이지...) 처음 요구 사항 명세, 상위 아키텍처 설계, 상세 설계 문서 범위와 양을 최소로 줄이기를 권장한다. 그리고 문서를 작성할 경우 항상 타임머신을 타고 미래로 간 다음에 미래 시점에서 과거를 기술하는 방법으로 위조하는 방법을 권장한다. 이렇게 두 가지 기본 원칙을 제안한 이유를 조금 자세히 설명할 필요가 있겠다. 일단 범위와 양을 줄여야 하는 가장 큰 이유는 불확실성 때문이다. 어차피 문서 작업도 작업이므로 많은 시간이 들어가는데, 나중에 변경이 일어날 경우 문서를 작성하느라 날려버린 기회 비용을 상실하는 동시에 문서 수정 작업이라는 이중 난관에 부딪힌다. 어차피 처음부터 완벽한 문서를 만들지 못하는 상황에서 분량도 늘이고 완성도도 높이려 애를 써봐야 모든 사람이 괴로을 뿐이다. 게다가 내용 채워넣기 식으로 만든 문서는 본질을 흐리게 만들어 나중에 투입되거나 유지보수하는 인력에게 있어 혼란을 일으킨다. 로버트 C. 마틴 큰 형님께서 '가장 좋은 주석은 주석을 달지 않을 방법을 찾은 주석'이라고 표현했듯이, 어떻게 보면 소프트웨어 소스 코드와 최종 매뉴얼만으로 설명이 가능한 경우가 최선이다. 다음으로 미래 시점에서 과거를 기술하는 방법을 제안하는 이유는 사람의 사고 특성상 기한이 많이 남은 일일수록 추상적으로 생각하고 기한이 짧은 일일수록 구체적으로 생각하기 때문이다. 사람들은 사후분석에 능하다. 어떤 일이 터지고 나서 현실화된 다음에는 어떻게든 이를 합리화하고 이해하려는 노력을 기울이게 되므로, 미래 관점에서 과거를 서술하는 방식이 훨씬 쉽다. 하지만 프로젝트를 발주한 내/외부 '고객'에게 이런 요청을 할 경우에는 반드시 반대 급부를 제시해야 한다. 공동 설계 참여를 요청하거나(그렇게 되면 설계 문서가 이상화되어야 하는 이유에 대해 인정할 수 밖에 없는 상황에 놓이게 된다. 변경이 일상다반사인 상황에서 고정된 최종 형태를 고집할 수 있을까? 고집부린 사람이 나중에 다 뒤집어 쓰게 되는 판국인데?) 중간 검수 과정을 둬서 요구 사항 문서와 아키텍처/설계 문서를 깔끔하게 정리해(즉 위조해서!) 다시 제공하겠다는 (즉 처음 프로젝트 시작 시점에서 만든 문서는 큰 범위와 목표만 기술한다) 약속을 하는 방법이 대표적인 해법이다. 프로젝트가 중간 정도 지났으면 이미 상당한 밑그림과 세부 사항이 파악되었으므로 이상적인 최종 형태에 가까워지기에 작성하기도 읽기도 쉬운 문서 작성에 한 걸음 다가간 상태기 때문이다.
지금까지 일반적인 내용을 설명했는데, 위조된 문서의 구체적인 예가 없을까? 다행스럽게도 로버트 C. 마틴 큰 횽아가 작성한 '클린 코드'의 14장 '점진적인 개선'은 지금껏 B급 프로그래머가 봐 왔던 위조 문서 중에서 백미를 자랑한다. 일단 최종 형상을 보여준 다음에 원래 엉망인 코드로 돌아와 설계 관점에서 차근차근 개선하는 과정을 위조해서(!) 보여주는데, (앞서 피해야 한다고 말했던) '프로그램 제작 과정'을 따르면서도 (최종 목적인) '프로그램 이해를 도와주는' 놀라운 업적을 달성했다. 이렇게 된 이유를 생각해보니 설계 결정이 어떤 식으로 일어났고 그 결과 코드가 어떻게 변경되었는지를 유기적으로 설명하기 때문이다. 물론 일반적인 프로젝트 진행 과정에서 (감히?) 이런 파격적인 방식으로는 문서 작성이 힘들겠지만, 디자인 관련 결정을 이상적인 방식으로 기술하는 좋은 본보기가 되므로 꼭 읽어보기 바란다. 다음으로 소개할 예는 The Architecture of Open Source Applications Vol I, II(AOSA라 약칭하겠다)다. 오픈 소스 아키텍처를 설명하는 내용으로 이미 많은 분들께서 알고 계신 이 책은 프로젝트가 흘러온 역사, 아키텍처의 선택 이유, 프로젝트에서 변경을 결정한 이유, 진행 과정에서 배운 교훈을 비교적 이상적인 프로세스에 가깝게 기술한 훌륭한 사례 연구를 담고 있다. 물론 프로젝트가 어느 정도 진행된 다음 기술된 사후해석으로 취급해 가치를 인정하지 않는 분들도 계시겠지만, 소프트웨어 큰 그림을 이해하기 위해 필요한 구성 요소가 무엇인지를 잘 드러내고 있으므로 아키텍처 문서가 어떻게 되어야 하는지 궁금하신 분들께서는 반드시 읽어보시기 바란다(실제로 오픈소스 프로젝트 문서에서도 점점 AOSA의 해당 내용을 언급하는 경우가 많아지고 있다. 그만큼 도움이 된다는 말이다).
결론: 개발자들이 합심해 죄책감없이 _뻔뻔_하게 문서를 이상적인 형태로 위조(!)함으로써 우리 시대 가장 골치 아픈 문제 중 하나인 문서화 작업을 즐겁고 생산적으로 바꿔놓을 수 있다면 얼마나 좋을까? 이와 관련해 다른 좋은 방법이나 의견 있으면 언제든지 알려주시기 바란다. 정말 바라건데, 좋은 아이디어는 함께 공유합시다.
EOB
