247. 클린 코드 네이밍 철학 (Clean Code Self-Documenting Naming)

핵심 인사이트 (3줄 요약)

1. 본질: 자가 설명 네이밍 (Self-Documenting Naming) 은 코드 자체가 문서가 되도록 변수·함수·클래스 이름을 의도(Why/What)를 드러내는 이름으로 짓는 클린 코드 (Clean Code) 의 핵심 원칙이다.
2. 가치: 주석 과잉 (Excessive Comments) 을 제거하고 코드의 진실 (Truth) 과 문서를 단일 소스로 일치시켜 유지보수 비용과 인지 부하를 동시에 줄인다.
3. 판단 포인트: "이 이름이 없어도 주석이 의도를 설명해야 하는가?" — Yes라면 이름을 다시 지어야 한다.

Ⅰ. 개요 및 필요성

로버트 C. 마틴 (Robert C. Martin, 일명 Uncle Bob) 은 "주석은 거짓말이다"라고 강조한다. 코드는 변하지만 주석은 종종 갱신되지 않아 허위 정보가 된다. 최선의 주석은 주석이 필요 없는 코드 자체다.

// 나쁜 예 — 주석이 코드를 설명
int d; // 경과 일수

// 좋은 예 — 이름이 의도를 표현
int daysSinceLastModification;

• 공개 API (Application Programming Interface) Javadoc
• 법적 주석 (저작권, 라이선스)
• 의도를 이름으로 표현하기 불가능한 정규식 패턴 설명
• TODO: 임시 표시 (단, 추적 티켓 번호 병기)

┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│ Problem      │──▶│ Core Idea    │──▶│ Expected Gain │
└──────────────┘    └──────────────┘    └──────────────┘

• 📢 섹션 요약 비유: "빨간 버튼 누르지 마시오" 대신 버튼 자체에 "비상정지"라고 쓰인 것이 더 믿을 수 있다 — 이름이 경고문보다 강력하다.

Ⅱ. 아키텍처 및 핵심 원리

나쁨 ◀─────────────────────────────────────────▶ 좋음
┌────────────┬──────────────┬──────────────────────────┐
│  암호형    │  주석 의존형  │  자가 설명형             │
├────────────┼──────────────┼──────────────────────────┤
│  int d;    │  int d; //일 │  int daysSinceLastVisit; │
│  void p(); │  // 처리     │  void processPayment();  │
│  String s; │  // 주소문자 │  String customerAddress; │
│  List l;   │  // 사용자목 │  List<User> activeUsers; │
└────────────┴──────────────┴──────────────────────────┘

┌─────────────────────────────────────────────────────┐
│               네이밍 추상화 계층                    │
├─────────────────────────────────────────────────────┤
│  패키지/모듈   com.company.billing.invoice          │
│    ↓                                                │
│  클래스       InvoiceGenerationService              │
│    ↓                                                │
│  메서드       generateMonthlyInvoiceForCustomer()   │
│    ↓                                                │
│  변수         customersWithUnpaidBalance            │
│    ↓                                                │
│  상수         MAX_INVOICE_LINE_ITEMS = 500          │
└─────────────────────────────────────────────────────┘

이름에 모든 정보를 넣는 것보다 클래스나 메서드의 맥락을 활용해 중복을 줄인다.

• 📢 섹션 요약 비유: 도서관 서가에서 "소설/한국/현대/채식주의자" 위치에 있는 책에 매번 "한국 현대 소설 채식주의자"라고 풀네임을 붙일 필요가 없다 — 위치(맥락)가 이미 설명한다.

Ⅲ. 비교 및 연결

• 📢 섹션 요약 비유: 지도에 매번 "이 점은 학교임" 메모를 붙이는 것보다, 처음부터 학교 모양 아이콘을 쓰는 게 낫다 — 범례(컨벤션)와 아이콘(이름)이 곧 설명이다.

Ⅳ. 실무 적용 및 기술사 판단

DDD (Domain-Driven Design) 의 유비쿼터스 언어 (Ubiquitous Language) 개념을 네이밍에 적용하면, 비즈니스 팀과 개발팀이 동일한 용어를 사용해 소통 오류가 줄어든다.

비즈니스 용어 → 코드 반영
"할인쿠폰 적용" → applyCoupon(Coupon coupon)
"재고 소진"     → isOutOfStock() / deplete(int qty)
"결제 승인"     → approvePayment(Payment payment)

• 이름만 보고 어떤 값/동작인지 알 수 있는가?

• 약어가 팀 전체에 공유된 약어인가?

• 클래스명이 명사이고 메서드명이 동사인가?

• 부울 변수가 is/has/can/should 접두사를 사용하는가?

• 컬렉션 변수명이 복수형인가 (users, orders)?

• 유지보수 비용 절감: 주석 동기화 비용 제거, 온보딩 시간 단축 (평균 30% 이상)

• 협업 효율: 코드 리뷰 시 의도 파악 시간 단축

• 자동화 도구: 정적 분석 도구로 이름 품질 측정 가능 (SonarQube 규칙 활용)

판단 체크리스트

1. 변경 전 동작을 고정할 테스트가 준비되었는가?
2. 냄새의 원인이 구조 문제인지 일회성 구현인지 구분했는가?
3. 리팩토링 단위를 작게 나눠 롤백 가능하게 했는가?
4. 명명·모델·패키지 경계가 함께 개선되는가?

• 📢 섹션 요약 비유: 수술실에서 집도의가 "3번 도구 주세요" 대신 "지혈 겸자 주세요"라고 말해야 간호사가 정확한 도구를 건넬 수 있다 — 전문 용어가 정확한 소통을 만든다.

Ⅴ. 기대효과 및 결론

자가 설명 네이밍 (Self-Documenting Naming) 은 코드를 협업 도구로 만드는 투자다. 좋은 이름은 한 번 짓지만, 나쁜 이름은 모든 독자가 매번 해석 비용을 치른다. "이 이름이 다음 개발자에게 뭘 말해주는가?"를 항상 먼저 묻는 것이 클린 코드의 시작이다.

확장 방향은 ① 정적 분석 자동화, ② 아키텍처 적합성 검증, ③ 작은 단위의 상시 리팩토링 문화 정착이다.

• 📢 섹션 요약 비유: 잘 쓴 이력서는 면접관이 추가 설명을 요청하지 않아도 된다 — 코드 이름도 그런 이력서여야 한다.

📌 관련 개념 맵

📈 관련 키워드 및 발전 흐름도

의도 드러내기 → 클린 코드 네이밍 철학 → ubiquitous language

👶 어린이를 위한 3줄 비유 설명

1. 서랍에 "물건들"이라고 적는 것보다 "양말", "속옷", "티셔츠"라고 적으면 열어보지 않아도 뭐가 있는지 안다.
2. 좋은 이름은 스티커 메모(주석)가 없어도 서랍 내용을 설명한다.
3. 코드도 이름만 잘 지으면 다른 사람이 코드를 "읽는" 게 아니라 "이해"하게 된다.