효율적인 개발과 유지보수를 위한 문서화의 힘

신입 개발자로 입사했을 때, 가장 어려웠던 점은 기존 코드로만 기능과 정책을 파악하는 것이였다.

문서화가 제대로 되어 있지 않고, 테스트 코드 조차 제대로 존재하지 않는 경우가 많아 팀 동료들에게 계속 물어봐야 했다.

또한, 코드 작성자가 퇴사자인 경우도 있어서 제대로 파악이 힘들었다.

이러한 과정에서 많은 시간이 소모되었던 것 같다.

 

장바구니 기능 서버 이전 프로젝트의 서버 담당자를 맡게 되었다. 관련 글은 다음 링크에 있다: https://comengin.tistory.com/851

Redis로 장바구니 구현하기: 예상치 못한 함정과 그 해결책

 

해당 프로젝트를 시작하며, 내가 겪었던 어려움을 다른 개발자들이 겪지 않도록 하기 위해 철저한 문서화를 결심했다.

 

프로젝트의 규모는 상당했다.

커밋 수 250개 이상, 새로 생성된 파일 100개 이상, 변경 줄 10,000 줄 이상이다. 테스트 코드가 많은 비중을 차지하지만, 그 외에도 많은 변경이 일어났다.

이 정도 규모의 프로젝트에서 문서 없이 코드만으로 정책을 파악하려면 엄청난 시간이 소요될 것이다.

 

문서화 내용은 다음과 같다.

1. 정책 및 요구사항 정리

-> 프로젝트의 목적, 주요 기능, 비즈니스 로직 등을 상세히 기술했다.

2. 용어 정리

-> 코드에서 사용되는 주요 용어들을 정의하고 설명했다.

3. 플로우 차트

-> 주요 프로세스의 흐름을 시각적으로 표현했다.

4. API 문서

-> 각 API의 요청/응답 형식, 파라미터 설명 등을 정리했다.

5. 스웨거 설명 추가

-> 스웨거 파라미터에 설명을 추가함으로써 클라이언트에게 명확하게 해당 필드에 대해 설명할 수 있게하였다.

 

아래 느낌으로 문서화를 진행하였다.

느낌만 봐주시길 바란다. 나는 대부분의 코드에 저렇게 주석을 달고, response에 각 파라미터를 설명한다.

 

특히 주석을 집중해서 저런식으로 많이 달았다.

가독성이라는게 주관적 성향이 너무 들어간다고 생각한다. 즉, 내 눈에는 가독성이 좋지만, 다른 사람한테는 좋지 않을 수도 있다.

그래서 주석을 같이 작성하여 플로우 및 의도 등을 같이 표현하는 경우가 많다.

 

문서화를 통해 얻은 것은 다음과 같다.

1. 빠른 온보딩: 새로운 개발자가 해당 기능을 유지보수 할 때, 문서를 통해 빠르게 전체 구조와 흐름 파악이 가능하다.

2. 유지보수 용이성: 추후 수정이 필요할 때 기존 정책과 로직을 쉽게 확인할 수 있어 유지보수가 수월해졌다.

3. 의사소통 개선: 용어 정리를 통해 팀 내 의사소통이 명확해지고, 오해로 인한 실수가 줄어든다.

 

문서화는 단기적으로 추가 작업처럼 느껴질 수 있지만, 장기적으로 봤을 때 개발 효율성과 코드 품질을 크게 향상시킨다고 생각한다.

특히, 팀 프로젝트에서는 더욱 가치가 빛난다고 생각한다.