이름과 가독성

"좋은 이름" 이 무엇인지에 대해서는 여러 책과 연구가 있습니다. 이 글은 Clean Code · Code Complete · Mythical Man-Month · 인지부하 (Cognitive Load) 이론을 사실 기준으로 정리합니다.

1. 이름이 닿는 자리

이름은 코드를 읽는 사람의 머리에 가장 먼저 닿는 표면. 이름이 정확하면 본문을 절반쯤 안 읽어도 의도가 전달되고, 이름이 흐리면 본문을 다 읽어도 의도가 흐립니다.

2. Clean Code (Martin, 2008)

2 장 "Meaningful Names" 의 규칙 (축약):

• Use Intention-Revealing Names — d 대신 daysSinceCreation 처럼 의도를 드러냄.
• Avoid Disinformation — 실제와 다른 함의를 가진 이름 (accountList 가 List 가 아니면 안 됨) 을 피함.
• Make Meaningful Distinctions — a1, a2, a3 같은 무의미 구분, Info / Data 같은 잡음 단어를 피함.
• Use Pronounceable Names — 발음할 수 있는 이름이 토론을 쉽게.
• Use Searchable Names — 한 글자 변수는 검색이 어려움.
• Class Names — 명사. Method Names — 동사.
• One Word per Concept — 한 개념에 한 단어 (get / fetch / retrieve 를 같은 의미로 섞지 않음).

3. Code Complete (McConnell, 2004)

11 장 "The Power of Variable Names" 의 지침 (축약):

• 이름의 길이는 변수의 영향 범위에 비례. 루프 인덱스 i 는 짧아도 되지만 모듈 전역 상수는 길게.
• 변수 이름의 최적 길이는 9 ~ 15 자 라는 사내 연구 결과 (IBM 등) 를 인용. 너무 짧지도 너무 길지도 않은 구간.
• 이름은 무엇 을 가리키는지 적고, 어떻게 구현되었는지는 가능하면 빼라.
• 부정형 이름 (isNotFound) 은 이중 부정에서 혼란.

4. 본질적 복잡성 vs 우발적 복잡성

Frederick P. Brooks Jr. 의 No Silver Bullet (1986, 후에 The Mythical Man-Month 1995 년판에 수록) 이 두 종류의 복잡성을 구분:

• Essential complexity (본질적 복잡성) — 문제 자체가 가진 복잡성. 비즈니스 도메인의 규칙 · 규제 · 물리적 제약. 줄일 수 없음.
• Accidental complexity (우발적 복잡성) — 도구 · 언어 · 구현 방식이 더하는 복잡성. 더 좋은 추상 · 이름 · 구조로 줄일 수 있음.

좋은 이름은 우발적 복잡성을 줄이는 가장 값싼 방법 가운데 하나. 이름 하나가 바뀌면 다섯 줄의 주석이 사라지는 경우가 흔합니다.

Brooks 의 핵심 주장은 도구 발전이 우발적 복잡성을 크게 낮추었으나 본질적 복잡성은 그대로 남아 있어, 어떤 단일 도구도 생산성을 한 자릿수 이상 올리지 못한다는 것 ("은총알은 없다"). 이름도 같은 의미로, 좋은 이름이 본질적 복잡성을 없애지는 못하지만 우발적 복잡성을 줄여 본질에 닿을 시간을 만듭니다.

5. 인지부하 이론

John Sweller 가 1988 년 논문 Cognitive load during problem solving 에서 정리한 학습 이론. 작업 기억 (working memory) 의 한계가 학습과 문제 해결에 영향을 준다는 뼈대.

분류:

• Intrinsic load — 자료 자체의 난이도. (≈ 본질적 복잡성)
• Extraneous load — 자료가 제시되는 방식이 더하는 부담. (≈ 우발적 복잡성)
• Germane load — 학습으로 이어지는 적극적 인지 활동.

코드를 읽는 일도 같은 모델로 설명. Programmer's Brain (Felienne Hermans, 2021) 같은 책이 이 이론을 코드 가독성에 적용. 흐린 이름 · 반복되는 마법 숫자 · 일관성 없는 스타일이 extraneous load 를 더한다는 시각.

6. 자주 쓰이는 휴리스틱

• 이름 하나에 한 의미 — 같은 개념을 두 곳에서 다르게 부르지 않음.
• 모르는 사람이 5 초 안에 의미를 짐작할 수 있는가? — 안 되면 다시 지음.
• 불리언은 질문 형태로 — isReady · hasError.
• 함수 이름은 부수 효과를 드러내라 — 순수 변환은 명사형 (toUpper), 상태 변경은 동사형 (saveUser).
• 컨벤션 일관 — camelCase / snake_case / PascalCase 는 언어 / 팀 표준을 따르고 한 저장소 안에서 섞지 않음.

7. 짧은 이름이 적합한 경우

이름이 길수록 좋은 것은 아닙니다. 짧은 이름이 적합한 경우:

• 좁은 스코프 (짧은 람다 · 작은 헬퍼) 의 임시 변수.
• 수학적 관습이 굳은 도메인 (x, y, z · dx, dy).
• 표준 라이브러리 관습 (i, j 인덱스).

McConnell 의 "영향 범위에 비례" 는 짧은 이름을 정당화하는 방향으로도 작용.

8. 자주 걸리는 자리

잡음 단어 — Manager · Helper · Util · Data · Info 가 늘어나면 의미가 흐려짐. 그 클래스가 무엇인지 한 단어 더 적는 편이 명확.

헝가리안 표기 — 타입을 이름에 박아 두는 관행 (strName · iCount) 은 강타입 언어가 일반화된 이후 가독성을 더 해친다는 평이 굳어짐.

약어 — 도메인 표준 약어 (http · url) 는 괜찮지만, 한 팀만 아는 약어 (accInf) 는 새 팀원에게 부담.

부정 이름의 부정 — if (!isNotEmpty) 같은 표현. 긍정 이름으로 바꾸는 편이 가독성에 유리.

이름 변경의 두려움 — IDE 의 안전한 리팩터 (이름 바꾸기) 가 충분히 발전. 흐린 이름을 발견하면 작은 PR 로 정정하는 비용이 점점 작아짐.

하고픈 말

이름은 우발적 복잡성을 줄이는 가장 값싼 도구. Clean Code 의 의도 드러내는 이름 + Code Complete 의 영향 범위 비례 길이 + 인지부하의 extraneous load 줄이기 셋의 결합이 좋은 이름의 토대. 이름 변경의 비용이 작아진 시대, 흐린 이름을 발견하면 그 자리에서 정정.

Next

• (philosophy 끝)

Robert C. Martin Clean Code · Steve McConnell Code Complete 2nd Edition · Frederick P. Brooks Jr. No Silver Bullet (PDF) · John Sweller Cognitive load during problem solving (1988) · Felienne Hermans The Programmer's Brain · Phil Karlton "two hard things" · Kent C. Dodds Make Impossible States Impossible 을 참고합니다.