코드보다 오래 남는 것 — 개발자에게 문서화란 무엇인가
"6개월 전 내가 짠 코드를 보면, 마치 남이 짠 것 같다." > 이 말에 공감하신다면, 이 글은 당신을 위한 글입니다.
시작하면서
솔직히 말씀드리면, 저도 처음엔 문서화를 거의 안 했습니다.
기능 구현하기도 바쁜데 문서는 무슨. 코드가 곧 문서 아닌가요? 라고 생각했습니다. 그 생각이 틀렸다는 걸 알게 된 건, 시간이 꽤 지나고 나서였습니다.
코드는 어떻게 동작하는지는 말해주는데, 왜 그렇게 만들었는지는 말해주질 않습니다.
그게 문제였습니다.
Why — 근데 왜 문서화가 필요한 걸까요?
우리는 생각보다 코드를 훨씬 많이 '읽습니다'
IDC 연구 결과가 꽤 충격적인데요, 개발자가 전체 업무 시간의 약 58% 를 기존 코드 파악하는 데 쓴다고 합니다.
절반이 넘습니다. 새 코드 짜는 시간보다 남의 코드, 혹은 과거 내 코드 읽는 시간이 더 길다는 겁니다.
그 시간을 줄이는 가장 직접적인 방법이 바로 문서화입니다.
문서가 없으면 실제로 이런 일들이 생깁니다
- 핵심 개발자가 퇴사하면 지식도 같이 사라집니다 — 코드는 남는데 "왜 이렇게 짰는지"는 아무도 모릅니다. 그 사람한테 물어볼 수도 없고요.
- 아무도 건드리지 않는 코드가 생깁니다 — 이유를 모르니까 함부로 수정했다가 뭔가 터질 것 같아서 그냥 둡니다. 팀 전체가 그 코드를 피해서 개발하게 됩니다.
- 온보딩이 끝없이 길어집니다 — 신규 팀원이 맥락을 파악하는 데 평균 3~6개월. 이 비용은 그 사람만 치르는 게 아니라 팀 전체가 치릅니다.
코드랑 문서는 하는 일이 다릅니다
| 코드 | 문서 | |
|---|---|---|
| 독자 | 기계 (컴파일러, 런타임) | 사람 (팀원, 미래의 나) |
| 말해주는 것 | 어떻게(How) 동작하는가 | 왜(Why) 그렇게 만들었는가 |
| 없으면 | 프로그램이 아예 안 돌아감 | 돌아가긴 하는데 아무도 이해 못 함 |
코드와 문서는 서로 대체하는 관계가 아닙니다. 하는 역할이 아예 다릅니다. 좋은 코드가 무엇을 하는지 보여준다면, 좋은 문서는 왜 그 선택을 했는지를 설명합니다.
What — 그래서 어떤 문서를 써야 할까요?
거창하게 생각하실 필요 없습니다. 실무에서 실질적으로 필요한 문서는 크게 다섯 가지입니다.
| 종류 | 예시 | 이걸 왜 쓰냐면 |
|---|---|---|
| 코드 레벨 | 주석, JSDoc, Docstring | 복잡한 결정의 이유를 코드 바로 옆에 남기려고 |
| README | 프로젝트 설명, 실행 방법 | "이게 뭔데, 어떻게 실행해?" 에 답하려고 |
| API 문서 | Swagger, Postman Collection | 인터페이스 계약을 말이 아닌 글로 남기려고 |
| 아키텍처 문서 | 시스템 다이어그램, ADR | 구조적 결정과 그 배경을 나중에도 알 수 있게 |
| 운영 문서 | 배포 절차, 장애 대응 런북 | "이거 어떻게 배포해요?"를 매번 설명 안 하려고 |
다 갖추실 필요는 없습니다. 지금 팀에서 제일 고통스러운 부분부터 시작하시면 됩니다.
How — 실제로 어떻게 쓰면 될까요?
원칙 1. "Why"만 써도 절반은 먹고 들어갑니다
문서 못 쓰는 분들의 가장 흔한 패턴이 있습니다. 코드를 그냥 말로 다시 쓰는 겁니다.
# 이렇게 쓰면 쓰나 마나입니다
i += 1 # i에 1을 더한다
# 이게 진짜 주석입니다
i += 1 # 외부 API의 페이지네이션이 1부터 시작하는 스펙 때문 (API 명세 3.2절 참고)
코드를 읽으면 무엇을 하는지는 그냥 보입니다. 주석이 말해줘야 하는 건 왜 그렇게 했는가입니다.
원칙 2. 문서는 코드랑 같이 업데이트해야 합니다
코드는 바뀌는데 문서가 그대로면, 그 문서는 없는 것보다 나쁩니다. 잘못된 문서를 믿고 몇 시간을 날리는 건 생각보다 자주 일어나는 일입니다.
PR 템플릿에 이거 하나만 넣어도 달라집니다:
## 체크리스트
- [ ] 관련 문서를 업데이트했습니다
코드 리뷰처럼, 문서 업데이트도 머지 조건으로 만드는 게 포인트입니다.
원칙 3. 완벽하게 쓰려다 아무것도 안 쓰게 됩니다
"나중에 제대로 쓸게"는 거의 항상 "영원히 안 쓴다"랑 같은 말입니다.
MVD(Minimum Viable Documentation), 최소 유효 문서 개념을 활용해 보세요. 두 줄짜리 메모도 괜찮습니다. 나중에 살을 붙이면 됩니다. 일단 존재하는 게 완벽한 것보다 낫습니다.
원칙 4. 자동화할 수 있는 건 자동화하세요
직접 안 써도 되는 문서들이 있습니다.
- JSDoc / Docstring → 함수에 붙이면 문서 사이트가 알아서 생성됩니다
- Swagger / OpenAPI → 코드에 어노테이션만 달면 API 문서가 만들어집니다
- Storybook → 컴포넌트 자체가 문서가 됩니다
- 테스트 코드 → 잘 짠 테스트는 "이 함수가 어떻게 동작해야 하는가"를 설명하는 살아있는 문서입니다
손으로 써야 하는 문서에 집중하시고, 자동화할 수 있는 건 기계에게 맡기세요.
원칙 5. ADR로 결정의 맥락을 남기세요
ADR(Architecture Decision Record). 적은 노력으로 가장 큰 효과를 내는 문서입니다.
## ADR-001: 상태 관리로 Zustand 선택
**상태**: 결정됨 (2024-03-15)
**왜 이 결정이 필요했냐면**
전역 상태가 늘어나면서 props drilling이 감당이 안 됨.
**뭘 선택했냐면**
Redux 대신 Zustand.
**왜냐면**
- 보일러플레이트가 훨씬 적음
- 번들 사이즈가 Redux의 1/10 수준 (8KB vs 80KB)
- 팀원 전원이 이미 써봤음
6개월 후에 "왜 Zustand 썼지?" 라는 질문이 나왔을 때, 누군가 다시 조사하러 앉을 필요가 없어집니다. 결정을 내린 시점의 맥락은 나중에 재현이 안 되기 때문입니다.
원칙 6. 런북으로 사람 의존도를 낮추세요
런북은 반복되는 작업을 절차로 만든 문서입니다.
## 배포 런북
1. `main` 브랜치 최신화 확인
2. 스테이징 배포 후 스모크 테스트
3. 프로덕션 배포 (`make deploy:prod`)
4. Sentry 에러율 5분 모니터링
5. 이상 있으면 롤백: `make rollback:prod`
런북이 없으면 그 작업은 특정 사람만 할 수 있는 일이 됩니다. 런북이 있으면 누구든 할 수 있는 일이 됩니다. 새벽 2시 장애 상황에서 런북의 유무는 대응 속도에 직결됩니다.
마치며 — 결국 문서화는 배려입니다
문서화는 거창한 게 아닙니다. 미래의 팀원에게, 그리고 6개월 후의 나 자신에게 "내가 여기까지 생각했어" 라고 말해주는 것입니다.
코드는 언젠가 사라집니다. 리팩터링되고, 삭제되고, 다시 쓰입니다. 그런데 좋은 문서는 그 판단의 흔적으로 남습니다.
당신의 코드가 사라져도, 좋은 문서는 남습니다.