코드 주석 정리 뒤에 남겨 두었던 린트 억제 지시문(eslint-disable*, @ts-expect-error 등) 207줄을 하나씩 감사했습니다. 82줄은 지워도 린트 결과가 바뀌지 않는 지시문이었고, 2줄은 경고가 나는 줄이 아닌 엉뚱한 줄을 겨누고 있었습니다. 억제 지시문도 주석처럼, 적혀 있으니 효과가 있겠거니 믿기 쉬운 코드였습니다.
앞 글 「코드 주석은 다섯 종류만 남깁니다」에서 pstack 의 주석 규칙인 Comment Sicko 를 모노레포 전체에 적용한 이야기를 적었습니다. 그때 린트 억제는 주석 판정 대상에서 빼고, 따로 감사하기로 했습니다. 이 글이 그 따로 한 감사의 기록입니다.
먼저 밝혀 둘 것이 있습니다. 이 레포의 ESLint 는 8.57.1 이고, 아래의 동작 설명은 이 판 기준입니다. 감사의 조건은 런타임 동작을 바꾸지 않는 것이었습니다. 207줄 가운데 1줄은 문서 속 예시여서 대상에서 빼고, 206줄을 처리했습니다. 지시문을 찾고 고치는 일은 단계마다 코딩 에이전트에게 맡겼지만, 이 글에서 다룰 것은 그 기준과 결과입니다.
린트 억제를 남겨도 되는 조건 — Comment Sicko 의 한 줄
Comment Sicko 가 남겨도 된다고 허락하는 주석 다섯 종류 가운데 하나가 린트 억제입니다. 조건은 짧습니다. 그 규칙이 틀렸거나, 지나치게 깐깐하거나, 스타일만 다룰 때만입니다. 규칙이 실제로 무언가를 지키고 있다면 억제할 것이 아니라 코드를 고쳐야 한다는 뜻입니다.
이 한 줄을 감사 기준으로 옮기면서 다섯 가지 원칙을 정했습니다.
- 규칙이 실제 버그·정합성·안전을 지키면 억제를 없애고 코드를 고칩니다.
- 규칙이 틀렸거나 스타일 전용이면 남기되, 사유를 지시문 안의
-- 사유로 답니다. ESLint 의 지시문 설명 문법입니다. - 같은 억제가 반복되면 인라인 대신 패키지 ESLint 설정으로 옮깁니다.
- 아무것도 억제하지 않는 지시문은 지웁니다.
- 억제 줄 위에 따로 있던 사유 주석은
-- 사유로 옮기거나 억제와 함께 지웁니다.
돌이켜 보면 이 원칙들은 대부분 «이 억제가 정당한가»를 묻고 있습니다. 넷째 원칙만 다른 질문을 합니다. 이 억제가 무엇을 억제하고 있기는 한가. 감사를 끝내고 나니, 207줄에 먼저 물어야 했던 것은 이쪽이었다는 생각이 들었습니다.
린트 억제 207줄 감사 결과
| 처리 | 줄 수 | 내역 |
|---|---|---|
| 타입으로 대체 | 24 | 로거 8 · DI 팩토리 3 · AI 응답 1 · 관리 화면 12 |
| 미사용 지시문 삭제 | 57 | 규칙이 이미 꺼진 곳 등 |
| 검사 밖이라 지시문만 삭제 | 25 | e2e 테스트 폴더 any 7 · require 15, ESLint 설정 없는 패키지 3 |
| 설정으로 이전 | 47 | 관리 화면 no-alert → 패키지 설정 한 곳 |
| 코드 수정으로 제거 | 2 | no-new 등 |
남김 + -- 사유 | 46 | exhaustive-deps 10 · no-img-element 8 · CJS require 7 등 |
| 손대지 않음 | 5 | 검증기 테스트 픽스처 문자열 안의 지시문 모양 텍스트 |
합하면 206줄이고, 문서 예시 1줄을 더해 207줄입니다. DI 팩토리 3줄은 NestJS 의 FactoryProvider 타입을 다시 쓰는 것으로, AI 응답 1줄은 SDK 가 제공하는 응답 타입으로 바꿨습니다.
미사용 57줄과 검사 밖 25줄, 합해서 82줄(약 40%)은 지워도 린트 결과가 바뀌지 않는 지시문이었습니다. 억제할 문제가 없었거나, 애초에 린트가 그 파일을 읽지 않았습니다. 여기에 설정으로 옮긴 47줄을 더하면, 인라인에서 사라진 지시문은 129줄입니다. 엉뚱한 줄을 겨누던 2줄은 지우지 않고 제자리로 옮겨 사유와 함께 남겼으므로, 이 82줄에는 들어 있지 않습니다.
엉뚱한 줄을 겨누던 eslint-disable-next-line
eslint-disable-next-line 은 바로 다음 줄에서 보고된 문제만 억제합니다. 그래서 규칙이 문제를 어느 줄에 보고하는지를 알아야 제대로 겨눌 수 있습니다. 여러 줄에 걸친 구문에서는 이 줄이 생각과 다를 때가 있습니다. 감사에서 이런 지시문이 2개 나왔고, 제자리로 옮기자 처음으로 효과가 생겼습니다.
react-hooks/exhaustive-deps — 의존성 배열 줄을 겨눠야 했습니다
useEffect(() => {
- // eslint-disable-next-line react-hooks/exhaustive-deps -- userCoords excluded: refetch only when station/sido change
if (stationName && sido) fetchRealtime(stationName, sido, userCoords);
+ // eslint-disable-next-line react-hooks/exhaustive-deps -- userCoords 는 뺀다: 측정소·시도가 바뀔 때만 다시 받는다
}, [stationName, sido, fetchRealtime]);exhaustive-deps 는 경고를 의존성 배열이 있는 줄에 보고합니다. 그런데 지시문은 그 위의 if 줄을 겨누고 있었습니다. 사유까지 영어로 성실하게 적혀 있었지만, 경고는 그동안 계속 나고 있었습니다. 지시문을 의존성 배열 바로 위로 옮기자 그 파일의 해당 경고가 1개에서 0개가 되었습니다.
no-explicit-any — 두 줄 아래의 any
- // any 사용 이유: 다양한 업로드 함수(이미지, 비디오 등)를 받는 범용 재시도 래퍼.
- // 각 업로드 함수의 반환 타입이 다를 수 있으므로 any 사용.
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
const uploadWithRetry = useCallback(
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any -- 이미지·영상 업로드의 axios 응답을 그대로 넘기는 재시도 래퍼라, 타입을 좁히면 시도 0회의 undefined 반환이 드러나 호출부를 바꿔야 한다
async (uploadFunction: () => Promise<any>, attempts: number = maxRetries) => {any 는 두 줄 아래의 매개변수 타입에 있었습니다. 앞 글에서 적었듯 레포의 코딩 지침이 «any 사용 시 반드시 주석으로 사유 명시»를 요구하고 있었고, 그래서 사유 주석은 두 줄이나 붙어 있었습니다. 지침이 요구한 것은 다 있었는데, 정작 억제는 효과가 없었습니다. 이것은 고치지 않고 남겼습니다. 대신 사유를 지시문 안으로 옮기고, 지시문을 any 가 있는 줄 바로 위에 두었습니다.
관리 화면 전체로는 경고가 83개에서 76개로 줄었습니다. any 를 타입으로 바꾼 것으로 6개, 제자리로 옮긴 지시문으로 1개입니다.
이 두 지시문은 둘 다 오류(error)가 아니라 경고(warn) 수준 규칙이라 빌드가 멈추지 않았습니다. 그래서 아무도 효과가 없다는 것을 알아차리지 못했습니다.
사유 주석이 틀렸던 any — unknown 이 있었습니다
로거의 민감 정보 마스킹 함수에는 이런 사유가 붙어 있었습니다.
- * any 사용 이유: 로깅 시스템은 어떤 타입의 데이터도 받아서 마스킹 처리해야 함.
- * 런타임에 객체 구조를 동적으로 순회하므로 정적 타입 정의가 불가능.
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function maskSensitiveData(data: any): any {
+function maskSensitiveData(data: unknown): unknown {
+ return typeof data === 'object' && data !== null ? maskObject(data) : data;
+}
+function maskObject(data: object): Record<string, unknown> {
+ const masked = (Array.isArray(data) ? [...data] : { ...data }) as Record<string, unknown>;«어떤 타입이든 받는다»는 unknown 의 정의 그 자체입니다. 런타임에 구조를 동적으로 순회하는 코드도 typeof 좁히기와 object 타입으로 표현됩니다. 정적 타입 정의가 불가능하다는 문장은 그럴듯했지만 사실이 아니었습니다. 로거에서만 억제 8줄이 이렇게 타입으로 바뀌었습니다.
앞 글에서 Comment Sicko 의 문장 하나를 옮겼습니다. «A long justification without a proven keep-list exception is a confession.» 증명된 예외 없이 늘어놓는 긴 정당화는 자백이라는 뜻입니다. 이 사유 주석이 그랬습니다. 길고 성실했지만, 그 길이는 any 가 필요하다는 증거가 아니라 아무도 unknown 을 시도해 보지 않았다는 흔적이었습니다.
아무것도 억제하지 않던 57줄 — --report-unused-disable-directives
공용 TS 린트 설정은 spec·test·scripts 파일에서 no-explicit-any 를 이미 꺼 두었습니다. 그런데 그 파일들에 eslint-disable-next-line @typescript-eslint/no-explicit-any 가 줄줄이 있었습니다. 꺼진 규칙을 다시 끄는 지시문입니다. 이런 것은 ESLint 에 미사용 지시문을 보고하게 하면 기계적으로 찾을 수 있습니다.
npx eslint --report-unused-disable-directives src설정 파일의 reportUnusedDisableDirectives 로도 같은 일을 할 수 있습니다. 이 보고가 잡는 것은 꺼진 규칙을 다시 끄는 지시문만이 아닙니다. 앞의 두 사례처럼 엉뚱한 줄을 겨눈 지시문도 그 줄에서는 아무것도 억제하지 않으니 똑같이 «unused» 로 나옵니다.
검사가 닿지 않는 곳의 린트 억제 25줄
백엔드의 e2e 테스트 폴더는 tsconfig 의 exclude 에 들어 있었습니다.
"exclude": ["node_modules", "dist", "test"]ESLint 는 타입 정보를 쓰려고 이 tsconfig 를 프로젝트로 지정합니다. tsconfig 가 제외한 파일은 타입 정보 기반 ESLint 가 파싱조차 하지 못합니다. 게다가 그 폴더는 린트 스크립트(eslint src)의 대상도 아니었습니다. 그곳의 지시문은 어떤 린트 실행에서도 읽히지 않는다는 뜻입니다.
any 억제 7줄과 require 억제 15줄이 여기 있었고, ESLint 설정이 아예 없는 패키지에도 3줄이 있었습니다. 스크립트 폴더도 ESLint 설정이 없어 같은 처지였습니다.
이 25줄은 지시문만 지우고 코드는 그대로 두었습니다. 그 폴더를 검사 대상에 넣을지는 별도의 결정으로 남겼습니다.
억제가 있다는 것은 그 규칙이 여기서 돈다는 증거가 아닙니다. 오히려 검사가 안 도는 곳의 억제는 검사가 돈다는 착각을 줍니다. 비슷한 예가 하나 더 있습니다. spec 을 포함하는 tsconfig 에는 원래 타입 오류가 915개 있었습니다. 그 정도면 그 범위의 타입 검사는 사실상 돌지 않고 있다고 보는 편이 맞다는 생각이 들었습니다.
같은 억제 47줄은 설정 한 곳으로 — no-alert
관리 화면에는 alert() 마다 // eslint-disable-line no-alert 가 붙어 있었습니다. 47줄이었습니다. 관리 화면은 내부 도구이고, 거기서 alert 를 쓰는 것은 정책입니다. 같은 억제가 47번 반복된다면 그것은 47개의 예외가 아니라 규칙과 정책이 어긋나 있다는 신호입니다. 그래서 인라인 47줄을 지우고 패키지 ESLint 설정 한 곳에서 규칙을 껐습니다.
rules: {
'no-alert': 'off',
},코드로 고친 것 — no-new
- expect(() => {
- // eslint-disable-next-line no-new
- new TokenService({ jwtSecret: '' });
- }).toThrow('JWT secret is required');
+ expect(() => new TokenService({ jwtSecret: '' })).toThrow('JWT secret is required');no-new 는 결과를 쓰지 않고 부작용만을 위해 new 를 부르는 코드를 막습니다. 화살표 함수가 생성 결과를 반환하게 하면 더는 부작용만을 위한 new 가 아니어서 규칙이 조용해집니다.
남긴 린트 억제 46줄 — 왜 남겼나
남긴 것 가운데 가장 많은 것은 react-hooks/exhaustive-deps 10줄입니다. 이것들은 고치지 않았습니다. 의존성을 더하면 effect 의 실행 빈도나 순서가 바뀔 수 있는데, 그 동작을 고정하는 테스트가 없었습니다. 테스트 없이 바꾸면 «런타임 동작을 바꾸지 않는다»는 조건을 지킬 수 없습니다. 대신 사유를 지시문 안에 달았습니다.
나머지는 no-img-element 8 · no-array-index-key 5 · CJS require 7 · no-control-regex 4 · naming-convention 4 · 기타 8줄입니다. 규칙이 그 자리에서는 맞지 않는 경우라, 역시 사유와 함께 남겼습니다.
한 번 지웠다가 되살린 것도 있습니다. 미사용 지시문을 지울 때 그 옆의 주석도 함께 지웠는데, 그 주석은 타임라인 트랙 판의 접근성 설계 근거였습니다. 일부러 slider 역할과 키보드 조작을 두지 않는 이유를 적은 것이었고, 리뷰에서 되살렸습니다. 지시문이 미사용이라고 해서 그 옆의 설계 근거까지 미사용인 것은 아니었습니다.
동작이 같다는 증거
린트·타입 검사·테스트·화면을 각각 따로 확인했습니다.
- 린트 — 백엔드
eslint src는 오류 0, 경고 186으로 전후가 같았습니다. 관리 화면은 오류 0, 경고는 83에서 76으로 줄었습니다. - 타입 검사 — 백엔드 빌드용 tsc 는 오류 0 입니다. spec 을 포함하는 tsconfig 의 오류 915개는 전후가 같았고, 바꾼 파일에서 새로 생긴 오류는 0개입니다.
- 테스트 — 백엔드 434 스위트, 8,770건이 통과했습니다. DB 가 필요한 23 스위트, 292건은 운영 자격 증명 없이 건너뛰었습니다.
- 화면 — UI 파일 30개를 바꿨습니다. 29개는 TypeScript 를 transpile 해 타입과 주석을 벗긴 JavaScript 가 기준과 같았고, 나머지 1개는 같은 로직을 헬퍼로 뺀 것입니다. Tailwind 가 생성한 CSS 는 6개 앱 모두 바이트까지 같았습니다.
정리 — eslint-disable 을 다루는 일곱 가지
다른 코드베이스에서 린트 억제를 정리한다면 이렇게 하겠습니다.
--report-unused-disable-directives(또는 설정의 같은 옵션)를 켭니다.eslint-disable-next-line은 규칙이 보고하는 줄을 겨눠야 합니다. 여러 줄에 걸친 구문에서는 특히 확인합니다.- 사유는 지시문 안(
-- 사유)에 둡니다. 위에 따로 단 사유 주석은 지시문과 떨어져 각자 썩습니다. - 같은 억제가 반복되면 그것은 규칙과 정책의 불일치입니다. 설정으로 옮깁니다.
any억제의 사유가 «어떤 타입이든 받는다»라면unknown을 먼저 시도합니다.- 검사가 닿지 않는 파일의 억제는 지웁니다. 그리고 그 파일을 검사에 넣을지 결정합니다.
- 동작을 바꿀 수 있는 억제(
exhaustive-deps등)는 테스트 없이 고치지 않습니다.
앞 글은 Comment Sicko 의 조건 하나로 끝났습니다. «proven true today on a live path», 오늘 실제로 도는 경로에서 참으로 증명된 것만 살아남는다는 조건입니다. 그때는 그 조건을 외부 제약 주석에 대어 보았는데, 억제 지시문에도 그대로 들어맞는다는 생각이 들었습니다.
지시문은 주석처럼 생겼지만 도구가 읽는 입력이고, 그래서 «읽히는가»와 «제 줄을 겨누는가»를 확인할 수 있습니다. 207줄 가운데 82줄은 읽히지 않거나 억제할 것이 없었고, 2줄은 제 줄을 겨누지 않았습니다. 사유가 아무리 성실하게 적혀 있어도, 그 지시문이 돌지 않는 자리에 있다면 그것은 효과가 아니라 효과가 있다는 믿음만 남깁니다.