본문으로 건너뛰기
wooncloud

참조 자동 갱신이 문서를 망가뜨린다, 링크를 데이터로 쓸 때

파일 이름을 바꾸면 참조를 자동으로 고쳐 주는 도구가 이름 때문에 생긴 문제를 기록한 문서까지 새 이름으로 바꿔 진단 근거를 지웁니다. 링크가 참조와 데이터 두 역할을 겸할 때 구분하는 방법입니다.

6분 분량

파일 이름을 바꾸면 그 파일을 가리키는 참조를 전부 자동으로 고쳐 주는 도구가 많습니다. IDE 의 rename symbol, 위키형 노트 앱의 링크 자동 갱신, 코드모드 스크립트가 다 같은 일을 합니다. 보통은 고마운 기능입니다.

그런데 "이 이름 때문에 참조가 이렇게 걸려 있다"는 사실을 기록해 둔 문서가 같은 저장소에 있으면 이야기가 달라집니다.

기록한 문장이 새 이름으로 바뀝니다

점검 리포트에 이런 줄이 있다고 해 봅시다.

`Setup Guide.md` 는 파일명 규칙(소문자, 하이픈) 위반입니다. 이 이름으로 걸린 [[Setup Guide]] 참조가 6곳 있습니다.

규칙에 맞게 setup-guide.md 로 rename 하면, 도구는 저장소를 훑어 이 리포트 안의 [[Setup Guide]] 까지 새 이름으로 바꿉니다.

`Setup Guide.md` 는 파일명 규칙(소문자, 하이픈) 위반입니다. 이 이름으로 걸린 [[setup-guide]] 참조가 6곳 있습니다.

문장은 문법적으로 멀쩡한데 의미가 어긋났습니다. 리포트는 옛 이름으로 걸린 참조를 기록한 건데, 이제는 규칙을 지킨 새 이름이 위반이라고 말하는 문장이 됐습니다. 왜 그 파일을 고쳐야 했는지 근거가 같이 사라집니다.

에러도 경고도 나지 않습니다. 도구 입장에서는 완벽하게 성공한 작업이니까요.

링크가 두 역할을 겸합니다

도구의 버그가 아닙니다. 한 문법이 두 가지 역할을 겸하는 게 원인입니다.

하나는 참조로서의 링크입니다. "저기로 가라"는 뜻이라 대상이 움직이면 따라가야 합니다. 다른 하나는 데이터로서의 링크입니다. "이런 문자열이 있었다"는 기록이라 절대 바뀌면 안 됩니다. 둘이 같은 표기를 쓰는 한 도구는 구분할 방법이 없습니다.

그래서 쓰는 쪽에서 구분을 만들어 줘야 합니다. 가장 싼 방법은 데이터일 때 인라인 코드로 감싸는 겁니다.

깨짐: [[Setup Guide]] 를 가리키는 참조가 6곳 있다
안전: `[[Setup Guide]]` 를 가리키는 참조가 6곳 있다

대부분의 도구는 코드 스팬과 코드 블록 안을 스캔 대상에서 제외합니다. 표기 하나 바꿨을 뿐인데 자동 갱신의 사정권 밖으로 나갑니다.

코드에서도 똑같습니다

마이그레이션 기록, 감사 로그 스키마, 폐기된 API 이름 목록처럼 과거의 이름을 보존하는 것이 목적인 데이터는 전부 이 함정에 걸립니다.

// 위험: 문자열 안까지 바꾸는 옵션으로 rename 하면 같이 끌려간다
const DEPRECATED_FIELDS = ['userName', 'userEmail']

리팩터링 도구가 "친절하게" 최신 이름으로 바꿔 주는 순간 이 목록은 존재 이유를 잃습니다. 의도를 주석과 별도 파일로 못박아 두는 편이 안전합니다.

// legacy-field-names.ts (리팩터링 제외 대상)
// v1 스키마의 필드명. 현재 코드에는 없다. 이 값은 rename 대상이 아니다.
export const LEGACY_FIELD_NAMES: readonly string[] = ['userName', 'userEmail']

자동 갱신이 있는 저장소에서 문서를 쓸 때 기준은 하나입니다. 이 참조가 가리키는 것인가, 기록하는 것인가. 기록이라면 코드로 감쌉니다.

스타일 가이드, 점검 리포트, 폐기 목록처럼 도구와 규칙을 메타로 서술하는 문서는 문서 전체가 데이터에 가깝습니다. 이런 문서에서는 살아 있는 참조를 기본값으로 두지 않는 편이 안전합니다.

참고