Self-Documenting Code vs. 주석: 대규모 코드베이스 유지 관리에서 얻은 교훈
Source: Dev.to
오래된 주석의 위험
주석의 가장 큰 위험은 구식화입니다. 코드가 리팩터링될 때, 개발자는 종종 연관된 주석을 업데이트하는 것을 잊어버립니다. 시간이 지나면 그 주석들은 “부패”해서 오해를 불러일으키고 위험해집니다. 자체 문서화 코드는 이 문제를 피할 수 있습니다. 논리가 바뀌면 “문서”(코드)도 반드시 바뀌어야 하기 때문입니다.
자체 문서화 코드의 기둥
1. 일반적인 약어 피하기
이름만으로 무엇을 그리고 어떻게를 전달해야 합니다. 별도의 설명이 필요 없어야 합니다.
// Bad
const d = 86400; // seconds in a day
// Good
const SECONDS_IN_A_DAY = 86400;2. 조건문 캡슐화
if 문 안에 복잡한 로직이 있으면 인지 부하가 증가합니다. 로직을 의미 있는 변수나 함수로 옮기세요.
// Bad
if (user.age > 18 && user.hasSubscription && !user.isBanned) {
// …
}
// Good
const canAccessPremiumContent =
user.isAdult && user.hasActivePlan && !user.isAccountFlagged;
if (canAccessPremiumContent) {
// …
}3. 살아있는 문서가 되는 강한 타입 사용
Enum과 인터페이스는 “매직 문자열”을 대체하고 유효한 옵션을 명시적으로 보여줍니다.
// Dart example
enum OrderStatus { pending, shipped, delivered }
// Instead of passing a raw String for status, use OrderStatus.언제 주석을 사용해야 할까
코드만으로는 맥락이나 왜라는 결정을 설명할 수 없을 때 주석이 유용합니다. 일반적인 상황은 다음과 같습니다:
- 우회 방법 – 예:
// Using a legacy loop here because the .map() polyfill fails in IE11. - 비즈니스 로직 이유 – 예:
// We trigger this sync twice to ensure the third‑party API acknowledges the handshake. - 중요 경고 – 예:
// CRITICAL: Do not change the order of these calls; it will cause a deadlock in the database.
비교: 장단점
| 접근 방식 | 장점 | 단점 |
|---|---|---|
| 자체 문서화 | • 논리와 항상 동기화됨 • 시각적 잡음 감소 • 더 나은 네이밍 강제 | • 외부 “왜”는 설명할 수 없음 • 변수명이 지나치게 길어질 수 있음 |
| 주석 | • 명확하지 않은 비즈니스 규칙 설명 • IDE 툴팁 제공 (예: JSDoc/DartDoc) | • 유지 보수 비용 높음 • “부패”하기 쉬움 • 종종 “냄새 나는” 코드를 가림 |
문서화 계층
-
레벨 1 – 로직
깨끗하고 모듈화된 코드를 작성하세요. “Step 1, Step 2”를 설명하기 위해 주석이 필요하다면 함수가 너무 큰 것입니다—분할하세요. -
레벨 2 – 타입
TypeScript, Dart 등과 같은 타입 시스템을 사용해 데이터 구조를 정의하세요. -
레벨 3 – 문서 문자열
공개 API에 JSDoc/DartDoc을 추가해 IDE 툴팁에 정보를 표시하도록 하세요. -
레벨 4 – 왜‑주석
깨끗한 코드를 읽고도 “왜 이렇게 했을까?”라는 질문이 남을 때만 주석을 추가하세요.
결론
시니어 엔지니어의 목표는 주석을 전혀 쓰지 않는 것이 아니라 불필요한 주석을 쓰지 않는 것입니다. 코드베이스의 모든 텍스트 라인은 가치를 더해야 합니다. 코드가 깔끔하면, 주석은 저수준 문법이 아니라 고수준 전략에 집중할 수 있어 전체 시스템을 이해하고, 유지보수하고, 확장하기가 쉬워집니다.