2005년 10월 29일에 네이버 블로그에 적은 글입니다.


새로운 문서화 작업 방식

8월부터 새로운 회사에서 일을 하게 되면서 저한테 맞는 문서화 방식을 적용해서 작업을 하기로 했습니다.

일단 저에 대해서 말하면 부끄럽지만 저는 아직도 설계에 대한 실력이 미천 합니다. 물론 한번 했던 일에 대해서는 할 자신이 조금 있지만 게임 개발 이라는게 왠만한 경력자가 아니면 했던 일을 또 하는 것은 쉽지 않고 거의 100% 다르지는 않지만 다른 일을 하게 된다고 생각합니다. 이렇다 보니 직접 프로그래밍을 들어가기 전에 구체적이고 체계적인 설계를 하기가 쉽지 않으면(책상에 있어도 잘 떠오리지 않더군요) 만약 설계를 했다고 해도 막상 프로그래밍에 들어가면 무지하게 변경을 하게 되더군요. 그래서 저는 프로그래밍 하기 전에 대략 약간 추상적인 형태의 설계를 잡고 제가 만들어야 되는 것에 대해서 기능별로 분리 후(물론 일단 할 수 있는 것만이라도) 그 기능을 하나 하나 구현해 나가면서 전체를 완성합니다. 물론 이 방법에는 하나의 그 전제가 하나 있습니다. 바로 끊임 없는 리펙토링 입니다.

만든 후 문제가 느껴지면 바로 리펙토링을 하면서 해소해 나가야지 다 만든 후 고쳐겠다는 생각을 했다가는 여러 개발 서적에서 나온 것 처럼 잘못된 설계로 다 엎어야 되는 상황에 빠지게 됩니다.

 

제가 하는 방식을 좀더 구체적으로 이야기 하면 저는 문서는 3 가지를 만듭니다. 유즈케이스 명세서, 시퀸스 다이얼그램, 활동 다이얼 그램  현재는 이 3개의 문서가 프로그래밍에 대한 중심이고(물론 소스의 주석은 기본이고요) 그 외에 사양서나 참고 사항에 대해서 따로 문서를 필요에 따라 만듭니다. 제가 구현해야 될 기능에 대해서 제 머리속에 구체적으로 떠오른다면 유즈케이스 명세서로 기능의 이름, 목적, 기본과정, 선 조건, 후 조건, 확장, 관련문서 등을 기록합니다.
이후 시퀸스 다이얼그램이나 활동 다이얼그램을 작성 합니다. 2개는 둘 다 만들어 질 때도 있고 필요하지 않다고 여겨 질 때는 필요한 것만 만듭니다. 제 개인적인 기준은 클라이언트, 서버 등의 여러 단계를 걸쳐가는 경우는 시퀸스 다이얼그램, 기능에 대한 상세한 흐름을 대한 것은 활동 다이얼그램을 이용합니다. 어떤 경우는 시퀸스 다이얼그램을 만들고 이 중 어떤 부분이 복잡하다고 생각되는 부분은 그 부분만을 따로 활동 다이얼그램을 만듭니다. 이것을 다하면 소스 코딩을 합니다.

물론 위에 같은 순서에 딱 맞추지는 않습니다. 어떤 경우는 먼저 소스 코딩을 하고 위의 문서를 만들기도 합니다. 다만 꼭 지키는 것은 기능의 완성된 시점은 코딩과 문서 작업이 다 끝냈을 때를 기준으로 하고 가능한 한 기능을 다 끝 내고 다음 기능을 구현하는 것을 원칙으로 하고 만약 소스를 수정하여 문서와 달라진다면 꼭 문서도 그 변경에 맞추어 변경해야 된다는 것입니다. 이렇게 하는 이유는 제가 처음에 이야기 했듯이 저의 경우는 아무리 문서화 의지나 시간이 있어도 그 양이 많아지면 너무 버거워져서 엄청나게 하기 싫어진다는 것 때문에 제가 쉽게 할 수 있는 양을 하고 또 소스에 특이한 부분은 그것을 만들 때 문서에 기록을 해야 그 당시의 상황에 대해서 좀더 정확하게 기록이 가능하다는 것이면 특히 문서와 소스가 서로 다르게 되면 문서화의 의미가 없어지게 때문에 꼭 같이 일치화 시키는 것을 중요하게 생각합니다. 


리펙토링

현재 제가 개발하는 방식에서는 리펙토링이 아주 중요합니다. 위에 말했듯이 저는 심사숙고한 설계 후 프로그래밍에 들어가는 것이 아니기 때문에 프로그래밍을 하다 보면 불합리한 구조, 이해 안가는 변수 및 함수 이름 등에 의해 수시로 알맞게 수정해야 됩니다. 다만 제가 의지가 약한 인간이다 보니 아무리 레펙토링에 대한 생각이 있어도 그 양이 제가 처리 할 양을 넘어서면 오히려 포기 하게 되기 때문에 언제나 작은 단위로 수시로 작업을 하는 것을 중요하게 생각합니다. 이러다 보니 때에 따라서는 문서와 코드가 불일치 될 확률이 상당히 높기 때문에 문서의 수정 완료를 전 리펙토링이 끝난 시점으로 보고 있습니다.

리펙토링은 코드의 수정 및 문서의 수정이 용이할 만큼 쌓였을 때 처리를 해야지, 이후 자꾸 수정이 있을 것 이라고 생각하여 모아서 하려고 하면 많은 양은 시간 부족에 의해 하지 못하니 자신의 성향에 맞게 잘 조절 해야 된다고 생각합니다.

 

문서화 툴

저는 문서화 툴은 따로 특별한 건 사용하지 않고 MS Office의 엑셀이나 파워포인트를 사용합니다. 다른 좋은 툴이 있지만 비싸고 사용 방법을 익혀야 되기 때문에 오히려 번잡하고 주위에 쉽게 있는 엑셀이나 파워포인트가 저한테는 딱 맞더군요. 특히 저 처럼 클래스 다이얼그램을 사용하지 않는 경우는 더 그렇다고 생각합니다. 다만 이후 Visual Studio .NET 2005가 출시되면 그 툴에 있는 것을 사용하면 좋지 않을까 해서 기대 중입니다.

참고로 저는 파워 포인트로 주로 상세 문서나 유즈케이스 명세서를 만들고, 엑셀로는 시퀸스 다이얼그램이나 활동 다이얼 그램을 만들고 있습니다.


신고
by 흥배 2008.03.20 23:18

티스토리 툴바