인수인계 문서를 쓰면서 내 코드를 다시 읽게 됐다
인수인계 문서를 작성하다 보니 당연히 알고 있다고 생각했던 코드에서 잘못된 부분을 발견했습니다. 문서화가 코드 이해도를 높여주는 과정을 정리했습니다.
팀에 새로운 개발자가 합류하게 되면서 기존 프로젝트들을 정리할 필요가 생겼습니다. 프로젝트가 여러 개다 보니 구두로 하나씩 설명하는 건 비효율적이었고, 문서로 남기는 게 서로에게 낫겠다고 판단했습니다.
문서를 쓰려고 코드를 열었는데
인수인계 문서를 쓰기 시작하면 가장 먼저 하는 게 "이 프로젝트가 뭘 하는 건지"를 설명하는 겁니다. 서비스 주소, 기술 스택, 환경 변수, 배포 방법... 이런 건 비교적 금방 정리됩니다.
문제는 "주요 기능"을 설명할 때 시작됩니다. 분명 내가 만든 기능인데, 막상 글로 설명하려니까 애매한 부분이 생깁니다. "이거 presigned URL이었나? File Gateway였나?" 같은 것들이요.
결국 코드를 다시 열어봤습니다.
실제로 잘못 기술했던 부분
관리자 대시보드의 파일 관리 기능을 정리하면서, 처음에 이렇게 썼습니다.
"파일 다운로드: 파일 Gateway를 통한 presigned URL 방식"
그런데 코드를 다시 읽어보니 이게 틀렸습니다. 실제로는 두 가지 방식이 섞여 있었습니다.
- 문서/이벤트 첨부파일: 백엔드 API에서 presigned URL을 직접 내려줌
- 상품 이미지: File Gateway에 file_token을 보내서 blob으로 받아옴
이 두 가지를 하나로 뭉뚱그려서 "File Gateway를 통한 presigned URL"이라고 쓴 거였습니다. presigned URL과 File Gateway는 완전히 다른 방식인데, 머릿속에서 대충 섞여 있었던 겁니다.
코드를 다시 읽고 나서야 정확하게 구분해서 쓸 수 있었습니다.
문서 구조를 어떻게 잡았는가
여러 프로젝트의 인수인계 문서를 쓰면서 반복적으로 쓰게 되는 섹션이 생겼습니다. 최종적으로 정리된 구조는 이렇습니다.
- 서비스 주소 - 운영/개발 환경 URL
- 기술 스택 - 사용된 프레임워크, 라이브러리
- 실행 스크립트 - dev, build, lint 등
- 환경 변수 - 각 변수의 역할 설명
- 라우팅 구조 - 어떤 페이지가 있는지
- 인증 - 로그인 방식, 토큰 관리
- 주요 기능 - 화면별 핵심 기능 설명
- 배포 - 배포 방법과 환경
- 참고사항 - 프로젝트 특이사항
이 중에서 가장 신경 쓴 건 주요 기능입니다. 코드를 안 열어봐도 "이 프로젝트가 뭘 하는 건지" 감이 잡히게 쓰려고 했습니다. 읽는 사람이 오늘 처음 입사한 신입이라고 가정하고 썼습니다.
가장 어려웠던 건 "어디까지 설명해야 하는가?"를 정하는 거였습니다. 인수인계 문서를 처음써보는 저로서는 그 기준을 정하기가 어려웠습니다. 최대한 인수인계 문서를 보고 프로젝트를 읽었을 때 도움을 줄 수 있는 서포터 역할을 하면 될 것 같다는 생각이 들었습니다.
API 엔드포인트는 넣지 않았다
처음에는 API 엔드포인트 목록도 넣었습니다. GET /api/products, POST /api/events 같은 것들이요. 그런데 다시 생각해보니 이건 코드에 이미 다 있는 정보입니다. Axios 인스턴스나 API 호출 파일을 열면 바로 보이는데, 문서에 중복으로 넣을 필요가 없었습니다.
인수인계 문서는 "코드를 읽기 전에 먼저 읽는 문서"입니다. 코드에서 바로 확인할 수 있는 건 빼고, 코드만 봐서는 알 수 없는 것들을 넣는 게 맞다고 판단했습니다.
- 왜 이런 구조를 선택했는지
- 환경 변수가 어디서 발급되는지
- 배포 시 주의할 점이 뭔지
이런 것들이 코드에는 없지만 인수인계 문서에는 있어야 하는 정보입니다.
문서를 쓰고 나서 달라진 점
문서를 쓰기 전에는 "이 기능은 이렇게 동작한다"고 막연하게 알고 있었습니다. 문서를 쓰고 나니까 정확하게 설명할 수 있게 됐습니다. 문서를 쓰는 행위 자체가 코드 리뷰의 역할을 한 셈입니다.
한 가지 아쉬웠던 건, 개발하고 시간이 한참 지난 뒤에 문서를 쓰려니 기억이 가물가물했다는 점입니다. "이거 왜 이렇게 했더라?" 싶은 부분이 생각보다 많았습니다. 앞으로는 기능을 추가하거나 구조를 변경할 때 바로바로 기록해두는 습관을 들여야겠다고 느꼈습니다. 나중에 한꺼번에 정리하는 건 결국 두 번 일하는 거였습니다.