위젯의 감춘 지역화 기능 문서에 명시
목차
프로젝트 공통 가이드 문서에 한 위젯이 지역화(i18n) 기능을 지원한다는 점을 명시했다. 겨우 한 줄 주석처럼 들릴 수 있지만, 소규모 팀에서 일하면서 느낀 건 이런 사소해 보이는 문서화가 얼마나 중요한지였다.
감춘 기능은 팀에 빚이 된다
지역화(i18n) 지원은 코드를 읽어도 처음엔 알아차리기 어렵다. 특히 위젯 같은 컴포넌트는 자동으로 현재 로케일을 감지하고 텍스트를 변환해주는 구조가 내장되어 있을 수 있는데, 그 구현이 어디 있는지 어떻게 동작하는지 깊게 파고들지 않으면 그냥 쓰는 쪽 입장에서는 "이게 되네?" 정도로만 끝난다.
이걸 모르는 팀원은 중복으로 지역화 처리를 하려고 시도할 수 있고, 또는 반대로 그 위젯에서 이미 제공하는 기능이 있는데도 모르고 직접 구현하느라 시간을 버릴 수 있다. 이런 식으로 감춰진 기능들은 팀 내에서 흩어지고, 코드 스타일도 들쑥날쑥해지고, 유지보수 포인트가 늘어난다.
문서화는 코드 리뷰의 가장 저렴한 형태
CLAUDE.md나 프로젝트 README 같은 팀 가이드 문서는 단순한 메모가 아니다. 이건 새 팀원이 온보딩할 때 제일 먼저 읽는 것 중 하나고, 기존 팀원들도 구현하기 전에 자연스럽게 "어, 이런 기능이 이미 있나?" 하면서 참고한다. 코드 리뷰에서 "이미 이 위젯에 그 기능이 있으니까 제거하세요"라고 지적하는 것보다, 처음부터 문서에 명시되어 있으면 시간이 훨씬 절약된다.
특히 팀 규모가 작을 때는 더 그렇다. 모든 팀원이 모든 코드를 외울 수 없으니까, 문서가 단일 진실의 공급처가 되어야 한다. 문서화를 미루거나 제대로 하지 않는 것은 사실상 나중에 다른 팀원들한테 일을 떠넘기는 것과 같다.
지역화 처리는 만만한 주제가 아니다
i18n을 제대로 구현하려면 신경 쓸 게 정말 많다. 언어별 텍스트는 당연하고, 날짜·숫자·통화 포맷, 문장 길이 차이에 따른 레이아웃 조정, RTL(오른쪽에서 왼쪽) 언어 대응, 폰트 선택 같은 세부 사항들이 있다.
만약 이미 그런 처리가 제대로 구현되어 있는 위젯이 있다면, 그걸 알리는 것만으로도 팀은 상당한 작업을 줄일 수 있다. 반대로 그 기능이 이미 있다는 걸 모르면, 또 다른 곳에서 비슷한 로직을 따로 구현하게 되고, 나중에 유지보수하거나 요구사항이 바뀔 때 여러 지점을 수정해야 하는 상황이 생긴다. 이건 기술 부채로 쌓인다.
작은 문서화가 모여 큰 생산성이 된다
이 변경은 너무 작아 보일 수도 있다. 하지만 팀의 지식 기반을 평탄하게 만드는 작업이다. 누군가는 이 위젯의 지역화 기능을 알고, 누군가는 모르는 상태를 방치하면, 코드 리뷰 빈도도 늘어나고, 개발 속도도 떨어진다. 불필요한 구현 시도나 리팩토링 요청이 반복된다. 문서 한 줄이 그런 반복을 줄일 수 있다면, 결국 팀 전체의 맥락 형성 시간이 줄어든다.
다음부턴 새로운 기능을 구현하거나 버그를 고칠 때 한 번 더 문서를 들춰보는 습관이 생길 것 같다. "혹시 이미 있는 기능 아닐까?" 하는 작은 의심이 중요하다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.