Thoughts2013.12.23 17:35

개발자는 대체로 문서 작업을 "오버헤드"로 받아들이는 경향이 있습니다. 품질 관리자 가운데는 이런 경향에 섭섭함을 토로할 분도 계시겠습니다만, 이건 엄연한 사실입니다. 개발자 가운데, 문서를 요구하는 관리자와 언쟁을 벌여본 경험이 없는 사람은 없을 겁니다. 


http://www.challengefuture.org/news/707


개발자에게 한가지 불행한 일은, 누군가는 그렇게 생산된 문서를 본다는 사실입니다. (편의상 문서 소비자라고 해 봅시다.) 그러니 문서화를 완전히 피할 방법은 없지요. 


문서 소비자에게 불행한 일은, 개발자가 생산한 문서 가운데 상당수에 적힌 내용이 실제 소프트웨어와 다르다는 사실입니다. 그런 상황이라면 소프트웨어를 만든 사람의 역량을 의심하게 되는 것도 무리는 아니지요.


이 불행은 무엇에서 비롯된 것일까요? 저는 '가치'에 대한 오해에서 비롯되었다고 봅니다. 개발은 고객에게 반드시 전달되어야 하는 가치를 만드는 행위입니다. 그렇다면 문서는 어떻습니까? 고객에게 보여주어야 하는 문서라면, '문서화'의 목적 또한 '고객에게 가치를 전달하는 것'이 되어야 마땅합니다. 내부 개발자들만이 공유할 문서라면요? 그럴 때는 이야기가 좀 달라집니다. 개발자들만이 볼 문서라면, 개발자들에게 최선의 가치를 전달할 수 있는 형태의 문서가 되어야 맞습니다. 관리자에게 보고할 문서라면요? 관리자들이 개발 진행상황을 쉽게 이해할 수 있도록, 최대한 간략화되고 개조식으로 정리된 문서가 되어야 맞을 겁니다. 그것이 관리자가 요구하는 '문서의 가치'이니까요. (관리자에게 가장 중요한 것은 '의사결정'임을 상기합시다.)


자. 그렇다면 우리는 비교적 쉽게, 문서화를 하는 데 있어 지켜야 할 원칙들을 뽑아낼 수 있을 것 같습니다. 문서화 작업에 있어서 우리가 지켜야 할 원칙들은, 의외로 우리가 개발할 때 지키는 원칙들과 비슷합니다. 


1. 단순성 (Simplicity) - 쓸데 없는 이야기를 하지 않는다. 


문서를 만들 때 중언부언 하지 않습니다. 가치에 반하는 것은 없앱니다. 개발자 내부적으로만 공유할 문서에 참여자들의 사인을 전부 받을 필요는 없습니다. 그런건 이슈 관리 시스템의 동료 검토 기능을 활용하면 됩니다. 개발자들만 볼 문서에 API의 상세 스펙을 넣을 필요는 없습니다. 그런건 JavaDoc에나 넣으면 됩니다.  단순하게 만들면 정보 중복이 줄어들고 관리 비용이 하락합니다. 필요한 내용만 넣고, 쓸데 없는 건 다 빼버리세요. 그런건 누가 요구할 때나 추가해 넣으면 됩니다 (규칙 5 참고).


2. 무결성 (consistency) - 소프트웨어의 실제 상태에 부합한다.


문서는 언제나 소프트웨어의 실제 상태에 부합해야 합니다. 고객이 어떤 사람이건 간에, 실제 상태에 부합하지 않는 문서는 언제나 실패한 문서입니다. 실패한 문서를 만들지 않는 몇 가지 방법이 있습니다. 첫 번째는 필요한 순간에 문서를 만들어 전달하고 해당 문서에 유효기간을 두는 것입니다 (규칙 4 참고). 두 번째는 개발자로 하여금 언제나 문서 창을 열어놓고 시스템을 변경할 때 마다 문서까지 변경하도록 요구하는 것입니다. 세 번째는 개발자가 언제나 주석에 가장 정확한 내용을 반영하도록 권하고, 필요할 때마다 주석에 적힌 내용을 갈무리해 문서를 만드는 것입니다. (세 번째 가이드라인을 따르는 문서가 JavaDoc같은 것입니다.) 


3. 독자 지향 (reader-oriented) - 문서를 읽을 사람을 고려한다. 


문서를 읽을 사람이 용역을 준 갑이라면 클래스 다이어그램이 필요할 것입니다. 그러나 고객이 시스템 사용자라면 클래스 다이어그램까지 그려진 문서를 주는 것은 과도합니다. 그런 경우에는 웹에 '사용자 가이드'와 'API 명세서'만 올려놓으면 충분합니다. 누가 문서의 고객인지를 생각하고, 거기 맞는 문서를 만드세요. 10명도 안되는 팀에서 다섯명 정도의 개발자들만이 돌려볼 문서라면, 아예 문서화를 포기하는 것도 생각해 보세요. 그런 팀에서라면 문서화 보다 잡담을 장려하는 쪽이 훨씬 나을지도 모릅니다. (그 팀의 진정한 목적이, 고객에게 '훌륭한 소프트웨어'라는 가치를 전달하는 것이라면 말이에요.) 


4. 적시성 (timeliness) - 문서가 필요한 시점을 고려한다. 


프로토타이핑이 진행된 결과로 이미 돌아가는 시스템이 있는 상태인데 굳이 설계 문서를 만들어서 클래스 다이어그램을 넣을 필요는 없습니다. 그런 것은 고객의 요구가 없는 한, 쓸데 없는 짓입니다. 문서가 여섯달 뒤에 필요한데, 지금부터 문서를 작성하는 것도 쓸데 없는 짓입니다. 그렇게 되면 문서의 무결성을 확보하기 위해 너무 많은 수고를 들여야 합니다 (규칙 2 참고). 언제 문서가 필요한지를 보고, 그에 맞는 문서화 계획을 세우세요.


5. 요구 지향 (demand-oriented) - 문서에 대한 고객의 요청을 고려한다. 


요청이 있다는 것은 고객이 문서를 통해 얻고자 하는 가치가 있다는 뜻입니다. 고객의 요구를 추정하다보면 문서에 너무 많은 내용을 담게 됩니다. 한 번에 완벽한 문서를 만들기 보다는, 고객의 요구를 받아들여 필요한 문서를 작성하는 것이 바람직합니다. 위키는 이런 용도에 적합한 시스템입니다. 위키에 기록된 사항만 언제나 무결하게 정리해 놓으면, 고객의 요구에 즉시 응답할 수 있습니다. 새로운 요청은 위키에 먼저 반영하여 고객의 반응을 살피고, 고객이 만족할 때 공식 문서로 변환할 수 있습니다. 그러니, 필요하지도 않은 문서를 만드는 데 너무 많은 시간을 쓰지 마세요. 


그리고 이 모든 원칙들이 너무 복잡하다면, 이것만 항상 생각하세요. '이 문서는 고객(문서를 읽을 사람)에게 어떤 가치를 주게 될까?' 이것만 기억한다면, 과도한 문서화의 함성에서 조금은 벗어나게 될 수도 있습니다.



저작자 표시 비영리 변경 금지
신고
Posted by 이병준

소중한 의견, 감사합니다. ^^

Extremely Agile/General2007.11.18 21:13
많은 프로그래머들이 개발을 하면서 문서 작성은 잘 하지 않습니다. 뭔가 좀 아는 사람들이 모여있는 개발 팀에서는 프로젝트 전반기에라도 가급적 설계 문서를 만들려고 애쓰는 경우가 태반인데 (아예 아무것도 하지 않는 팀도 있긴 합니다. 스파이크 솔루션이라도 간단히 만들어보면 좀 낫습니다만...) 그런 경우에라도 막상 프로젝트가 끝날 때 보면 문서의 상태와 개발 결과물의 상태가 심히 어긋나 있는 경우가 대부분입니다. 뭔가 조금씩 틀리고 잘 맞지 않죠.

극단적으로 보자면, 주석문의 상태와 코드의 상태가 다른 경우도 있습니다. 프로그래머가 코드를 변경하면서 주석문을 재검토하는 것을 잊은 것이죠.

이런 문제에 대한 '현실적인 해결책'들이 여러가지 나와 있습니다. 몇 가지를 열거해 보면

1. 코드의 흐름은 코드가 말하게 하라
2. 문서를 만들면서 코딩하라

뭐 이정도가 있겠습니다. '코드의 흐름은 코드가 말하게 하라'는 것은 가급적 코드에 '그 하는 일'이 명료하게 드러나게 만들라는 뜻입니다. 이렇게 하자면 함수 이름을 잘 지어야 하겠고, 변수 이름을 잘 지어야 하겠고, 가급적 각각의 함수는 그 길이가 짧아야 합니다. 너무 긴 함수는 이해하기 어렵기 때문입니다.

하지만 그렇다고 하더라도 코드만 보고 전체 코드의 얼개를 파악하기란 지난한(혹은 지랄맞은) 일입니다. 그래서 그런지, 저는 다른 사람의 코드를 읽어야 하는 일이 생기면 엔간하면 밑바닥부터 코드를 다시 짜고야 마는 못된 습성이 있었습니다. 지금은 그러지 않으려고 굉장히 애를 많이 쓰는 편입니다만...

그러므로 가장 좋은 해결방법은 2번입니다. "설계 후 코딩하라"는 말을 "프로젝트 전반기에 설계하고 프로젝트 후반기에 코딩하라"는 식으로 아둔하게 해석하는 대신, "설계 후 코딩"에 드는 간격을 최소한 줄여보자는 것입니다.

저는 작업을 할 때 큰 모니터에는 설계 문서를 띄워 놓고 설계를 해 나갑니다. 설계가 끝나면 바로 옆에 있는 노트북에서 개발을 합니다. (좋은 키보드는 데스크탑에 물려놓고 대체 뭐하는 짓인지 ㅋㅋ) 개발을 하다가 뭔가 이상하다 싶으면 즉석에서 테스트를 하고 설계를 변경할 때도 있습니다만, 가급적 설계를 바꿀 때에는 그 사실을 먼저 문서에 반영하고 그 다음에 코딩에 들어가도록 하고 있습니다.

이렇게 하는 것의 장점은 몇가지가 있습니다만, "조엘 온 소프트웨어"의 조엘 말대로, "코드에 손을 대기 전에 먼저 생각을 해 본다는" 점이 가장 큰 장점이겠습니다. 물론 아주 숙련된 프로그래머의 경우에는 프로그램의 설계 전부가 테스트 코드부터 시작해 일사천리로 뻗아 나오게 되는 경우도 있겠습니다만, 대부분의 프로그래머는 그렇지 않으므로, 가급적 설계에 조그마한 변경이라도 가할라치면 문서를 함께 변경해 가는 쪽이 낫겠습니다.

물론 자주 문서에 손대는 것을 싫어하는 프로그래머도 많습니다만, 조엘 아저씨의 말대로 설계가 충실한 코드는 정작 코드 자체를 작성하는 데 드는 시간은 짧습니다.

그런데 대부분의 프로그래머가 그 말을 믿지 않는 가장 큰 이유는

(1) 설계부터 구현까지에 이르는 시간 간격이 지나치게 크기 때문이고
(2) 그렇다보니 정작 코딩을 하기 시작했을 때 즈음에는 요구사항이 바뀌어 다시 설계를 해야하고
(3) 결국은 '재설계'에 투여할 시간이 부족하여 설계를 건너뛰게 되고
(4) 그러다 보니  코드 작성에 드는 시간이 그다지 줄어들지 않게 되기 때문이죠.


이것이 바로 Waterfall 식의 개발 방법의 가장 큰 병폐입니다.
 
그러니 문서를 업데이트 하는 데 드는 시간을 아까와 하지 않고, 개발과 병행해 나가는 편이 낫겠죠.


루비 프로그램 개발화면

루비 프로그램을 짤때, 설계 문서를 옆에 놓고 설계를 고쳐 가면서 SciTE로 코딩하던 장면




신고
Posted by 이병준

소중한 의견, 감사합니다. ^^

  1. 입사한지 얼마 되지는 않아서 회사의 솔루션 분석 하고 있습니다. 코드에 주석이 너무 없고 소개 문서도 없어서 맨땅에 해당하는 기분이네요 그래도 어느정도 파악이 되어 c로 된 솔루션을 자바로 변경하는 작업을 할 예정인데 문서화를 해야겠다는 생각이 절실히 드네요. 이제부터라도 확실히 해서 후배들이 들어왔을때 쉽게 접근하도록 해야겠네요^^ 좋은 글 감사합니다.

    2008.09.26 11:22 신고 [ ADDR : EDIT/ DEL : REPLY ]
    • 감사합니다. 너무 많은 문서화도 바람직하지 않습니다만, 그렇다고 아주 문서화를 도외시할 수는 없으니, 가급적 문서와 코드의 상태를 잘 맞출 수 있도록 하는 방법을 찾는 것이 좋겠습니다. :-)

      2008.09.26 12:38 신고 [ ADDR : EDIT/ DEL ]