마크다운 주석 — HTML 주석 문법과 미리보기

마크다운 주석의 가장 강한 용도는 편집입니다. 필요한 곳에 지시를 남기는 것. 템플릿은 모든 섹션 위에 <!-- 아래 API 키 칸을 채우세요 -->를 달 수 있고, 변경 이력은 미공개 항목 옆에 <!-- 항목 작성 완료, 법무 검토 대기 -->를 둘 수 있으며, 긴 README는 오래된 섹션을 지우는 대신 주석 처리로 역사를 보존할 수 있습니다. 텍스트는 파일에 남으므로 git blame이 귀속을 보여 주고, 이후 편집자는 마커만 지우면 내용을 복원합니다.

두 번째 용도 집단은 구조적입니다. 디버깅 중 망가진 코드 펜스를 잠시 빼두기, 숫자가 확정될 때까지 초안 표를 숨기기, 생성된 목차가 들어갈 자리 표시하기 — 모두 마크다운 주석의 자연스러운 일입니다. 반면 주석이 되어서는 안 되는 것은 보안 장치입니다. 내용은 공개된 파일과 함께 배포됩니다. 모든 마크다운 주석은 표시되는 예의만 갖춘 공개 텍스트로 취급하세요.

공유 저장소에서 마크다운 주석은 다음 편집자에게 보내는 메시지입니다. 날짜를 넣고, 이니셜을 넣고, 다음에 무엇을 해야 하는지 쓰세요. <!-- TODO(mia): 3분기 출시 전 가격 확인 -->은 <!-- 확인 -->보다 1년을 더 삽니다. 일이 끝났으면 비석으로 고쳐 쓰는 대신 마크다운 주석 전체를 지우세요. 역사는 버전 관리의 몫이지 주석 퇴적물의 몫이 아닙니다.

주석이 쌓이는 속도는 문서가 자라나는 속도만큼 빠릅니다. 분기마다 한 번, TODO와 FIXME 접두어로 시작하는 마크다운 주석을 검색해 그 시점의 상태를 확인하는 습관을 들이세요. 끝난 일은 마커째 지우고, 여전히 유효한 메모는 날짜를 갱신해 주세요.

주석은 문서의 안내판이지만 지도가 아닙니다. 세 문서 이상에 걸쳐 반복되는 안내라면 주석 대신 문서 상단의 안내 섹션으로 옮기는 편이 낫습니다. 한 곳에서만 필요한 짧은 메모 — 그것이 마크다운 주석이 가장 잘하는 일입니다.

주석과 삭제의 경계도 기억해 두세요. 지워도 되는 역사라면 버전 관리의 커밋에 맡기는 것이 옳고, 문서를 읽는 동안 필요한 안내라면 본문으로 승격시키는 것이 옳습니다. 주석은 그 두 사이, 즉 지금은 조용히 있지만 나중에 다시 필요할 수 있는 정보의 임시 거처입니다.

주석 문화는 팀마다 다르지만 좋은 문서는 결이 비슷합니다. 주석은 짧고, 명확하고, 지워질 날을 알고 있습니다. 이 세 가지가 갖춰진 주석은 문서의 조용한 보조석이 되고, 갖춰지지 않은 주석은 언젠가 문서의 짐이 됩니다. 쌓이기 전에 다듬는 습관이 그 차이를 만듭니다.

주석을 읽는 미래의 자기 자신을 동료로 생각하세요. 반년 뒤의 나는 오늘의 맥락을 잊은 채 파일을 열고, 주석이 말을 걸어 옵니다. 그때 반가울 메모인지를 판단 기준으로 삼으면 주석의 양과 질이 저절로 정리됩니다.