결정-0058: 문서는 규범만 담고 현황은 참조로 지정한다

상태

Accepted

문서가 낡는 것은 성실함의 문제가 아니라 구조의 문제입니다. 코드에서 읽을 수 있는 것을 문서에 옮겨 적으면 두 벌이 되고, 두 벌 중 하나는 반드시 낡습니다.

버전 표, 파이프라인 흐름, API 시그니처, 설정 값이 대표적입니다. 이것들은 코드와 설정 파일이 이미 정확하게 갖고 있으며, 문서의 사본은 갱신을 잊는 순간 오정보가 됩니다. 오정보는 정보가 없는 것보다 나쁩니다.

문서를 코드와의 시간 관계로 나누고 부류별로 원본 위치를 분리합니다.

구분	준수 지침 (Do)	금지 지침 (Don't)
기재 범위	규범만 기재합니다	현황을 옮겨 적습니다. 버전 · 파이프라인 · 시그니처 · 설정 값이 해당합니다
강제 수단	기계로 강제 가능한 규칙은 실행 가능한 규칙으로 옮기고 문서에는 근거와 기계가 못 잡는 것만 남깁니다	강제 가능한 규칙을 문서에만 적습니다
편성 기준	독자가 문서를 여는 계기로 나눕니다	프로세스 분류 체계를 편성 축으로 씁니다
규칙 표기	규칙마다 강제 여부를 함께 적습니다	자동 차단되는 것과 리뷰로 보는 것을 구분 없이 나열합니다

등록부는 코드에 둡니다. 에러 코드 접두사 목록, 억제 목록, 마스킹 대상 목록이 여기 해당합니다. 문서에 두면 코드를 고칠 때 문서를 함께 고쳐야 한다는 것을 기억해야 하지만, 코드에 두면 그 자리가 곧 등록부라 잊을 수 없습니다.

구분	내용
장점	코드와 문서가 어긋날 수 없습니다
단점	왜 그렇게 했는가는 코드에 없습니다. 생성 가능한 것은 현황뿐입니다
기각 사유	기각이 아니라 부류를 나누는 근거입니다. 후행 문서는 생성하고 병행 문서는 사람이 씁니다

구분	내용
장점	언제 열어도 최신입니다
단점	동기화 자체가 상시 작업이 되고, 그것을 미루는 순간 문서가 아니라 부채가 됩니다
기각 사유	납품과 공유용 산출물은 요청 시점에 저장소 원본에서 1회 생성하는 편이 낫습니다

문서가 낡는 속도가 크게 줄어듭니다. 규범은 자주 바뀌지 않고 현황은 문서에 없기 때문입니다.

감수하는 것은 문서 하나만 읽어서는 전체를 알 수 없다는 점입니다. 버전을 알려면 빌드 스크립트를, 강제 규칙의 목록을 알려면 설정 파일을 함께 봐야 합니다. 그래서 문서는 규칙을 적을 때마다 원본이 어디인지를 함께 적습니다.