페이스북의 Server Side Architecture Group에 마틴 파울러의 글이 올라와 번역하였습니다. 제가 소프트웨어 문서화 쪽에 굉장히 관심이 많아서 논문 주제도 문서화로 잡기도 했었고, 특히 그 중에 애자일 문서화 쪽에 관심이 많아 이 글을 그냥 지나칠 수가 없었네요. 점심 시간을 투자하여 번역해 보았습니다. 급하게 번역하느라 발 번역입니다만, 즐겨주세요. 뿅~
* 원문 : http://martinfowler.com/bliki/CodeAsDocumentation.html
코드의 문서화(CodeAsDocumentation) - 마틴 파울러
애자일 방식의 공통 요소들 중 하나는 프로그래밍 작업을 소프트웨어 개발 내에서 중요한 역할로 높였다는데 있습니다. 소프트웨어 엔지니어링 커뮤니티들이 늘상 그러하는 것 이상으로요. 이는 소프트웨어의 기본적인 문서화보다 코드 그 자체를 주요한 문서로 분류하도록 하고 있습니다.
이와 동시에 저는 일반적인 오해에 대해 반론해야 할 필요성을 느꼈습니다. 이러한 원칙은 코드가 유일한 문서라고 말하는 것이 아닙니다. 저는 익스트림 프로그래밍(Exetreme Programming) 진영에서 이런 말을 하는 것을 종종 들었지만서도, 익스트림 프로그래밍 운동의 리더들이 이런 말을 하는 것은 단 한 번도 본 적이 없습니다. 일반적으로 코드의 내용을 보충하는 역할로서 문서화는 더욱 필요합니다.
코드가 문서의 기본적인 형태라는 이론적인 근거는 코드가 충분히 상세하고, 충분히 정확한 역할을 하는 문서라는 것이며, 이는 잭 리브스(Jack Reeves)가 저술한 에세이 "What is Software Design? (소프트웨어 기획/설계란 무엇인가?)"에서 설득력을 만들어 주었습니다.
이런 원칙은 중요한 결과 하나를 야기합니다. 그것은 프로그래머들이 자신의 코드가 명확하고 읽기 좋은지 확신하는 데에 그들의 노력을 투입하는 행위가 중요하다는 점입니다. 코드가 문서화다라고 말함의 의미는 특정 코드 베이스(code base)는 좋은 문서라고 말하는 것이 아닙니다. 다른 문서화들과 마찬가지로, 코드도 깔끔하게 설명되었을 수도 있고 횡설수설일 수도 있습니다. 본질적으로 코드는 다른 종류의 문서화보다 명료하지 않습니다. (게다가 절망적으로 다른 종류의 문서들 역시 의미가 모호할 수 있습니다. 저는 횡설수설 표현된 채 조직을 채찍질하는 UML 다이어그램들을 많이 보았습니다.)
분명히 대부분의 코드 베이스들이 썩 좋은 문서는 아닙니다. 그렇기에 코드만이 문서라 선언하여 다른 종류의 문서들을 제외하려는 결론은 그릇된 판단이며, 코드는 나쁘기 때문에 나쁜 문서라 말하는 것 역시 오판입니다. 코드를 깔끔하게 작성하는 것은 충분히 가능한 일이며, 사실 확신하건데, 대부분의 코드 베이스들은 훨씬 더 깔끔하게 작성할 수 있습니다.
저는 코드가 읽기 어려운 이유 중 하나로 사람들이 코드도 문서가 될 수 있다는 점에 대해 심각히 받아들이지 않기 때문이라 생각합니다. 코드를 명확하게 만들고자 하는 의지가 없다면, 코드 그 자체가 명료해 질 수 있도록 도약할 기회는 적어집니다. 그렇기에 코드를 명확히 하기 위한 첫 번 째 단계는 코드도 문서가 될 수 있다고 받아들이는 것입니다. 저는 대부분의 프로그래머들이 프로그래밍을 시작할 때 이런 부분을 배우는 것으로부터 명확한 코드 작성이 시작한다고 생각합니다. 저의 선생님도 깔끔한 코드를 만드는 데에 많이 집중하지 않았고, 가치를 두지 않는 듯 했으며, 이를 어떻게 구현해야 하는 지에 대해서도 많은 이야기를 하지 않았습니다. 우리와 전체 산업은 코드 명확성의 가치 평가를 더 많이 강조해야 합니다.
다음 단계는 어떻게 하는 지를 배우는 것인데요, 저는 여러분들께 베스트 셀링(Best selling)한 기술서의 저자가 드리는 조언을 제안합니다. "이 세상에 리뷰만한 것은 없습니다. 많은 사람들이 제 책을 읽은 후 의견 교환하는 과정을 거치지 않고 책을 출간한다는 것은 생각조차할 수 없습니다." 이와 마찬가지로 코드 내에서 어떤 부분이 이해가 잘되고, 잘 되지 않는 지에 대해 다른 이들의 의견을 받아 코드를 깔끔하게 만드는 행위 만큼 중요한 것은 없습니다. 다른 사람들이 여러분들의 코드를 읽을 수 있는 가능한 많은 방법을 찾으세요. 다른 이들이 어떤 부분을 쉽게 이해하고, 무엇이 혼동을 일으키는 지 알아 보세요. (예, 페어 프로그래밍(Pair programming)은 이를 행할 수 있는 훌륭한 방법입니다.)
보다 구체적인 조언으로 저는 프로그래밍 스타일에 대한 좋은 서적들을 읽으시기를 권장합니다. 코드 컴플리트(Code Complete)는 가장 먼저 살펴보셔야 합니다. 그리고 예상하시는 바와 같이 리팩토링(Refactoring)을 추천합니다. 많은 리팩토링을 거칠 수록 코드는 더욱 더 깔끔하게 만들어 집니다.
여러분들은 늘 다양한 관점에서 반론하는 사람들을 찾아야 합니다. (여러분들이 코드 중 일부를 떼어 개별 코드 권한을 가지고 연습하는 경우에도) 코드 베이스는 팀이 소유하고 있음을 기억하세요. 프로페셔널한 프로그래머는 팀의 요구를 반영하여 자신의 개인적인 스타일을 변경할 준비가 언제든 되어 있습니다. 따라서 여러분들 중 누군가 삼중 연산자(ternary operator)를 선호하시더라도, 만약 여러분들의 팀이 그걸 이해하기 쉽지 않아 한다면 사용하지 마세요. 여러분들이 자신만의 프로젝트를 진행하신다면 각자 자신만의 스타일 대로 프로그램하셔도 됩니다만, 여러분들이 어떤 팀에 속해 있다면 그 팀의 요구를 따라주는 것이 좋습니다.
