본문 바로가기

소프트웨어이야기

도대체 얼마나 자세히 적어 달라고?!


소프트웨어 개발자들에게 문서 작성은 고역이 아닐 수 없습니다. 그래서 문서는 소프트웨어를 개발한 후에 후배들에게 소프트웨어에의 스펙과 구조를 설명하기 위해서 작성하곤 합니다. 이런 경우에는 문서의 효용성도 별로 없을 뿐더러 문서가 제대로 작성되었는지 알기도 어렵습니다. 또 개발자들은 기억을 더듬어서 문서를 작성하기도 어려울 뿐더러 이러한 작업은 하기 싫은 고역이 될 수 밖에 없습니다.

소프트웨어를 개발하는데 있어서 필수적인 문서의 대부분은 개발한 내용을 정리하기 위해서 만드는 것이 아니고, 소프트웨어를 개발하는데 필요한 내용을 앞 단계에서 작성하는 것입니다.

즉, 설계를 하기 전에 스펙을 작성하고
구현을 하기 전에 설계서를 작성하고
테스트를 하기 전에 테스트 계획 및 TCL(Test Case List)를 작성합니다.

하지만 현실에서는 이렇게 작성된 문서를 가지고 다음단계 작업이 잘 안 된다는 문제가 있습니다.
즉, 다른 개발자가 작성한 스펙을 가지고 설계 및 구현(코딩)을 할 수가 없는 경우가 대부분입니다.

스펙을 제대로 작성하려면 남이 설계할 수 있을 정도로 상세하게 적어야 하는데, 잘못하면 백과사전이 되고 또는 흔히 빈약한 스펙서를 작성합니다. 이렇게 되면 스펙을 작성한 사람이 또 설계자에게 계속 스펙을 설명해줘야 합니다. 

이 글을 읽고 있으면서 이것이 뭐가 문제라고 생각하신다면 이미 가내수공업식 개발에 익숙해지신 겁니다. 한 개발자가 스펙도 작성하고 설계, 구현, 테스트를 모두 다하는 이런 가내수공업식 개발은 회사는 성장의 한계에 부딪히고, 개발자는 성장하지 못하는 악순환에 빠지기 쉽습니다.

개발문서는 그 문서를 보고 다음단계의 개발자들이 충분히 일을 진행할 수 있을 정도로 상세해야 합니다.
따라서 상세화 정도는 상황에 따라서 다르다는 것을 알 수 있습니다. 설계자가 해당 제품에 대해서 빠삭하게 알고 있으면 기능스펙을 적당히 적어도 문제가 없을 것이고, 신입사원에게 일을 시키려면 좀더 자세히 적어야 할 것입니다. 

또한, 좀더 작은 양으로 이해 가능한 문서를 작성하려면 소프트웨어를 다양한 뷰에서 바라보고 적어 주는 것이 좋습니다. 따라서 스펙을 작성할 때는 소프트웨어를 인터페이스에서 바라본 모습, UI에서 바라본 모습 그리고 기능, 비기능적인 내용을 적어주면 기능에 대하여 많은 양을 설명한 것보다 더 이해하기 쉽습니다.  설계에 있어서도 소프트웨어의 아키텍처를 데이터 관점, Flow 관점, 시간의 흐름, 시스템의 상태 등 다양한 관점에서 바라본 모습을 적당히 표현해 주는 것이 하나를 자세히 적어 주는 것보다 좋습니다.

매우 추상적인 글을 적어 놓은 것 같지만, 실제 개발문서를 제대로 적기 시작하면 잘 적었는지? 못 적었는지는 명확하게 구분 됩니다. 작성된 문서를 가지고 다음 단계 개발자들이 별 무리 없기 개발을 할 수 있고, 문서가 거의 바뀌지 않는다면 잘 작성된 것이고, 그렇지 않으면 잘 작성되지 않은 것입니다.

그래서 이를 위해서 기법을 쫓기 보다는 실제로 필요한 것이 무엇인가 생각하고 실질적인 접근이 필요합니다. 잘못 익힌 기법은 독이 될 수 있습니다.

이미지출처 : Microsoft Office Online
* 이 포스트는 blogkorea [블코채널 : 꿈꾸는 소프트웨어 개발자 세상] 에 링크 되어있습니다.