레거시 시스템 유지보수에서 문서화 부재는 예상치 못한 복잡성으로 이어진다
TPS 시스템 유지보수 투입 초기에 가장 먼저 느낀 건 막막함이었다.
코드는 있는데 왜 이렇게 짰는지 모르겠고, 여기서 저기로 어떻게 이어지는지도 불분명했다. 어떤 테이블이 어떤 화면에서 쓰이는지, 특정 메서드가 어떤 조건에서 호출되는지—알고 싶은 게 있을 때마다 코드를 직접 따라가야 했다. 퍼즐 조각을 하나씩 맞춰가는 것과 비슷했는데, 맞추고 나서도 전체 그림이 머릿속에 잘 잡히지 않았다.
레거시 시스템을 다루는 건 오래된 건물을 리모델링하는 것과 비슷하다. 겉으로 보이는 것보다 훨씬 많은 것들이 얽혀 있고, 건드리면 예상치 못한 문제들이 계속 발견된다. 그 복잡성의 상당 부분은 코드 자체가 아니라 문서화의 부재에서 비롯된다.
물론 그 코드를 처음 만든 사람들도 당시엔 바빴을 것이다. 납기에 쫓기면 문서는 자연스럽게 뒤로 밀린다. 하지만 그 결과는 고스란히 유지보수 담당자에게 넘어온다.
폐쇄망이라는 추가 제약
이 프로젝트는 폐쇄망 환경이었다. 외부 패키지를 그냥 가져올 수도 없고, 배포 과정도 복잡했다. 소스를 잘못 배포했다가 문제가 생기면 재수정하는 절차가 까다로웠는데, 이걸 설명하는 내부 가이드가 없으니 처음 겪을 때는 온전히 혼자 해결해야 했다.
폐쇄망 환경에서는 로컬 저장소 구축도 별도로 챙겨야 한다. 인터넷이 안 되는 환경에서 의존성을 관리하는 방법을 그때 처음으로 제대로 고민하게 됐다.
문서화는 다음 사람을 위한 일
이 경험이 준 교훈은 단순하다. 문서화는 선택이 아닌 다음 사람에 대한 예의에 가깝다. 완벽한 문서가 아니어도 괜찮다. 왜 이렇게 설계했는지, 이 부분에서 주의할 점은 뭔지—짧은 코멘트 하나라도 남겨두는 것과 아무것도 없는 것은 실제로 큰 차이가 난다.
레거시 시스템을 파악하는 가장 빠른 방법은 직접 코드를 따라가는 것뿐이라는 현실이 바뀌지는 않는다. 그 수고를 조금이라도 줄여줄 수 있는 게 문서다.
연결 (이유)
- 구체적인 예외처리 없이는 에러 원인 파악도 사용성도 기대할 수 없다 — 동일 TPS 프로젝트에서 문서화 부재가 예외처리 부재로 이어진 직접적 사례
- DB 통신 횟수를 줄이는 것이 성능 개선의 핵심이다 — 레거시 시스템 성능 개선 과정에서 얻은 교훈으로, 같은 프로젝트의 다른 측면을 다룸
- 클라우드 네이티브 아키텍처는 단순 마이그레이션이 아닌 아키텍처 재설계를 요구한다 — 레거시 복잡성이 단순 마이그레이션으로는 해결되지 않는 이유를 맥락으로 설명