pstack 의 주석 규칙 Comment Sicko 의 원문은 남겨도 되는 주석을 법적 고지, 우리가 바꿀 수 없는 외부 제약, prettier-ignore 와 일부 린트 억제, 공개 API 계약, 이슈·RFC 링크의 다섯 종류로 정합니다. 이 규칙으로 모노레포의 주석을 지우며, 지우는 도구와 지운 결과가 주석 말고는 같다는 것을 증명하는 도구를 따로 두었습니다.

이 글은 그 검증 방법과, «주석을 지워도 동작은 바뀌지 않는다»는 예측이 어긋난 예외를 적은 2026년 10월 28일 기준 작업 도중의 기록입니다. 비JS 파일의 주석은 작업 브랜치에서 지웠고, JS/TS 주석은 지울 대상을 판정만 한 단계입니다.

주석 삭제 검증 — 지우는 도구와 증명하는 도구를 따로 두었습니다

목록은 TypeScript 파서로 만들었습니다. git 이 추적하는 JS/TS 파일에서 주석을 전부 뽑아 주석마다 id 를 붙였는데, id 는 «파일 + 주석 원문 + 같은 원문의 파일 안 순번»의 해시입니다. 줄 번호를 쓰지 않았기 때문에 줄이 밀려도, 리베이스를 해도 같은 판정을 다시 적용할 수 있습니다. 뽑은 주석은 판정에 앞서 지시문, 빈 블록의 유일한 주석, 제외, 판정 후보로 나눴습니다.

삭제 도구는 판정 데이터를 읽어 주석의 범위만 지웁니다. 줄 단독 주석이면 그 줄째, 줄 끝 주석이면 앞 공백까지, JSX 의 {/* */} 는 중괄호째 지웁니다. 지시문과 빈 블록 주석은 id 가 넘어와도 지우지 않습니다.

증명은 서로 독립인 세 겹으로 두었습니다. 삭제와 검증을 같은 방법으로 하면, 삭제가 놓친 것을 검증도 같이 놓치기 때문입니다.

  1. 검증기 — 변경 전후 파일을 각각 TypeScript 의 구문 트리(AST)로 파싱해, 주석·공백·따옴표 종류·괄호·속성 이름 따옴표·숫자 표기·JSX 의 의미 없는 공백을 정규화한 노드 열을 비교합니다. 같으면 PASS 이고, 지시문 주석이 사라지거나 생기면 FAIL 입니다.
  2. 컴파일 산출물 비교 — 백엔드는 tsc --removeComments 로 만든 JS 를 전후로 바이트 비교합니다. JS/TS 를 실제로 지우는 단계에서 할 예정이고, 아직 하지 않았습니다.
  3. 패키지별 검사 — 타입 검사·린트·빌드·테스트입니다.

검증기의 테스트는 15건입니다. 주석만 지운 쌍은 PASS, 토큰 하나를 지운 쌍은 FAIL 이어야 합니다. (a + b) * c 를 a + b * c 로 바꾸면 FAIL, (c) 를 c 로 바꾸면 PASS 입니다. let → const, !x → -x, extends → implements, import → import type 은 모두 FAIL 이고, // eslint-disable-next-line no-console 이나 /* #__PURE__ */ 를 지운 것도 FAIL 입니다. 동작이나 번들 결과가 바뀔 수 있는 지시문이기 때문입니다.

이 검증기로 왕복 시험도 했습니다. 23개 패키지에서 고른 실제 파일 60개(테스트 파일, tsx·jsx, js·mjs·cjs 를 섞었습니다)에서 후보 주석 2,475개를 전부 지우고 prettier 를 돌린 뒤 검증기에 넣었습니다. 원본 그대로와 비교하면 58개가 PASS 였습니다. 실패한 2개는 주석 때문이 아니라, prettier 의 Tailwind 클래스 정렬 플러그인이 className 순서를 바꾼 탓이었습니다. prettier 를 적용한 원본과 비교하자 60개 모두 PASS 였습니다.

pstack 의 원칙 Prove It Works 에는 «When verification fails, suspect the observation method before suspecting the system»이라는 문장이 있습니다. 검증이 실패하면 시스템보다 관찰 방법을 먼저 의심하라는 것인데, 이 두 건이 그런 경우였습니다. 틀린 것은 지운 쪽이 아니라 비교의 기준이었습니다.

CSS·Dockerfile·셸·YAML 등의 주석 — 실제로 지운 2,346줄

비JS 파일의 주석은 작업 브랜치에서 이미 지웠습니다. 대상 82개 중 57개 파일에서 줄 단독 주석 2,346줄을 지웠고(css 1,021 · 셸 458 · Dockerfile 424 · yaml 290 · env 116 · python 21 · html 13 · toml 3), diff 는 삭제뿐이고 추가는 0줄입니다. 남긴 것은 외부 제약 68개 범위와 라이선스 1개, 그리고 기능 주석 25개(셔뱅 24개, # -*- coding 1개)입니다. 언어마다 «같다»를 증명하는 방법은 달랐습니다.

언어전후가 같다는 증명
YAMLyaml.safe_load 결과 일치
Pythonast.dump 결과 일치
CSSpostcss 로 주석 노드를 뺀 직렬화 일치
Dockerfile주석·빈 줄을 뺀 명령 열 일치, docker build --check, 백엔드 이미지 1회 실제 빌드
셸shfmt -mn(최소화) 결과 일치, bash -n

함정도 있었습니다. YAML 블록 스칼라(run: |) 안의 # 줄은 주석이 아니라 값입니다. 그 안에 PowerShell 주석이 들어 있어도 YAML 입장에서는 문자열입니다. Dockerfile 의 RUN <<EOF 본문 안 # 도 Dockerfile 주석이 아닙니다. 줄 끝 # 은 따옴표 해석이 필요해서 건드리지 않았습니다.

Dockerfile 에서 지운 것의 실물은 이렇습니다.

plaintext
-# ============================================
-# Backend Dockerfile (Multi-target)
-# ============================================
-# Targets:
-#   api    — API 서버 (0.5 CPU / 512MB)
-#   worker — Scheduled Jobs (0.25 CPU / 256MB)
 FROM public.ecr.aws/docker/library/node:24-alpine AS builder
-# pnpm 활성화
 RUN corepack enable && corepack prepare pnpm@10.30.3 --activate
-# 1. Workspace 설정 파일 복사
 COPY pnpm-lock.yaml pnpm-workspace.yaml package.json tsconfig.base.json ./

반대로 남긴 것은 NEXT_PUBLIC_* 값이 빌드 시점에 번들에 인라인된다는 것, Docker 명명 볼륨이 처음 붙을 때 이미지 안 디렉터리의 소유권을 물려받는다는 것, 네이티브 최적화(GGML_NATIVE)로 빌드한 바이너리가 다른 CPU 에서 SIGILL 로 죽는다는 것, ENTRYPOINT 와 CMD 의 덮어쓰기 규칙 같은 외부 제약입니다.

커밋 메시지에는 이런 판단을 남겼습니다. «이번 변경은 주석 줄만 삭제하므로 주석·빈 줄을 뺀 명령 열이 전후 동일함을 파일마다 증명했고(RUN <<EOF 본문은 제외), 이것이 빌드 성공보다 강한 근거다.» 빌드가 성공했다는 사실은 «같다»를 증명하지 않습니다. Prove It Works 도 대리 지표나 자기 보고, «it compiles» 로 추론하지 말라고 적습니다.

«주석을 지워도 동작은 바뀌지 않는다»

처음의 예측은 «주석 삭제는 런타임을 바꾸지 않는다. 바꿀 수 있는 것은 지시문 누락뿐이다»였습니다. 실제로는 지시문 말고도 예외가 둘 있었습니다. 하나는 ASI(자동 세미콜론 삽입)입니다.

javascript
function before(x) {
  return /*
  */ x;
}

function after(x) {
  return x;
}

console.log(before(1), after(1));

실행하면 undefined 1 이 찍힙니다. 줄바꿈이 든 블록 주석은 파싱할 때 줄바꿈처럼 취급되어, return 뒤에 세미콜론이 자동으로 들어갑니다. 주석을 지우면 반환값이 바뀝니다. 다른 하나는 JSX 텍스트 사이의 빈 표현식 주석입니다.

plaintext
<p>foo{/* c */}
bar</p>          렌더 결과: foobar

<p>foo
bar</p>          렌더 결과: foo bar

JSX 는 줄바꿈이 섞인 텍스트의 줄들을 공백 하나로 잇습니다. 그런데 사이에 {/* */} 가 끼어 있으면 두 텍스트가 따로 놓여 공백 없이 붙습니다. 그래서 검증기가 이 두 경우를 FAIL 로 잡게 했습니다. 다만 60개 파일 왕복 시험에서 이런 경우는 0건이었습니다.

지시문도 생각보다 종류가 많았습니다. 원문은 prettier-ignore 와 린트 억제만 말하지만, 실제로 «주석처럼 생긴 도구 입력»은 이만큼 있었습니다.

plaintext
JS/TS 파일
eslint-disable*, @ts-ignore, @ts-expect-error, prettier-ignore,
istanbul / c8 ignore, webpack 매직 주석, @vite-ignore,
/// <reference>, @jsx 프래그마, @jest-environment, #__PURE__,
sourceMappingURL, // falls through, @license, /*!, @deprecated,
JS 파일의 JSDoc 타입(@type, @typedef — checkJs), 셔뱅

그 밖의 파일
Dockerfile # syntax=, # shellcheck, # yaml-language-server:,
# type: ignore, # noqa, # -*- coding

조건이 붙는 것도 있습니다. // falls through 는 다음 토큰이 case 나 default 일 때만 지시문입니다. 이 레포의 «falls through» 2건과 «no default» 4건은 산문이었습니다. @internal 은 stripInternal 을 쓰는 tsconfig 가 있을 때만 의미가 있는데, 이 레포에는 없었습니다. JSDoc 타입은 JS 파일에서만 지시문이고, TS 파일에서는 산문입니다. 지시문의 개수 자체도 정의에 따라 558개(초기의 넓은 기준)에서 259개(최종 기준)까지 달라졌습니다.

더 현실적인 위험은 삭제 커밋에 딸려 오는 다른 변경이었습니다. 후보 파일 2,783개 중 107개는 한 번도 prettier 를 거치지 않은 파일이었습니다. 이런 파일은 주석을 지우는 커밋에서 prettier 가 함께 돌며 Tailwind 클래스 순서까지 바꾸고, 그러면 검증기가 FAIL 합니다. 그래서 판정 전에 포맷 정리만 담은 커밋을 따로 두었습니다.

커밋 훅(lint-staged)도 같은 종류의 문제를 만듭니다. 훅은 스테이징한 파일 전체를 린트하기 때문에, 그동안 린트를 거친 적 없는 파일의 기존 오류가 주석 삭제 커밋을 막습니다. 그런 오류는 따로 고친 커밋을 먼저 둡니다.

정리하면, 주석만 지운 변경이 동작을 바꾸지 않았다는 증명은 지우는 방법과 다른 방법으로 해야 했고, 언어마다 «같다»를 재는 방법도 달랐습니다. 그리고 줄바꿈이 든 블록 주석과 JSX 텍스트 사이의 빈 표현식 주석처럼, 주석만 지워도 동작이 바뀌는 예외가 있었습니다. AST 검증기로 «주석 말고는 같다»를 증명한 주석 삭제 커밋이 앱 6개의 Tailwind 생성 CSS 를 바꿔 놓은 일은 «Tailwind CSS 는 주석도 읽습니다»에, 어떤 주석을 남기고 지울지 판정한 기준과 결과는 «코드 주석은 다섯 종류만 남깁니다»에 적었습니다.