문서화

팀원 중 머피라는 팀원이 서버의 트래픽이 올라가 server.xml내에 maxThead 의 설정을 200에서 500으로 connectionTimeout 을 20000에서 60000으로 늘리게 되었어요. 하지만 당장의 에러는 줄었지만 문서화를 하지 않았죠. 하지만 몇 달 뒤 머피가 퇴사하고, 서버에 부하가 걸리면서 원인 분석을 하게 됐어요. 보아하니 스레드가 500개 까지 점유하게 되면서 JVM 힙을 과도하게 사용되고 타임아웃이 60초로 느린 요청이 지속적으로 스레드를 오래 점유하게 되는 현상이 발생했어요. 이 설정이 언제 어디서 발견되었는지 확인이 매우 어렵고 이전 개발자의 의도가 어떻게 되어 이렇게 처리했는지 확인이 필요하게 되죠.

만약 문서화가 제대로 이루어졌다면, 해당 조치가 임시 조치였다는 것을 바로 파악할 수 있었을 거예요. 이후 다른 개발자가 소스를 분석하거나 오류를 수정할 때도, 왜 이렇게 처리했는지 의도를 명확하게 알 수 있죠.

이와 같은 예시를 들었어요. 사실 이러한 의도와 사례는 제가 짧지만 다양한 업무를 진행하면서도 많이 접할 수 있어요. 그렇다면 어떻게 문서화 작업을 해야할까요.?

제가 개인적으로 생각할때의 문서화의 중요 포인트를 아래와 같이 정리해 보았어요.

네임스페이스

사실 네임스페이스가 가장 중요하다 생각해요. 문서화랑 “무슨 상관?” 이라 말할 수 있어요. 하지만 의도와 목적에 맞는 네임을 잘 작성하게 될 경우 문서화 하지 않아도 이전 개발자의 의도를 파악할 수 있어요.

불필요한 설명

명확한 설명이 필요해요. 하지만 소스만 봐도 충분히 이해할 수 있는 부분을 장황하게 풀어서 문서화 하게 될 경우 오히려 불필요한 시간 낭비가 될수 있어요.

살아있는 문서

정말 잘 작성된 문서임에도 독이 되는 경우가 있죠. 바로 문서의 최신화에요. 문서를 최신화 하지 않을 경우 최신화 되지 않은 문서를 신뢰하여 해당 문서를 갖고 개발하게 될경우 해당 프로그램의 장애로 이어질 수 있어요.

의사결정 기록

머피는 A와 B 방식중 현재 A 방식이 옳다 판단하여 A 방식을 채택 하였어요. 하지만 담당자가 바뀌며 머피 2세가 등장하여 해당 소스를 확인하고 B 방식이 더 낫다고 판단하여 다시 분석하게 돼요. 이렇게 A와 B중 왜 A를 채택하였으며 ‘어떠한 이유’로 채택 했는지에 대해 확실하게 문서화 해야해요.