“이 변수 tmp2가 대체 뭐였더라?” 3주 전의 내가 짠 코드를 들여다보며 현재의 내가 머리를 싸맵니다. 클린 코드 네이밍 규칙을 익혀야겠다고 결심하는 순간은 보통 이렇게 찾아옵니다.
이 글은 규칙을 나열하는 대신, 초급 개발자가 실제로 마주치는 장면들을 따라가며 변수 이름 짓는 법을 풀어 보겠습니다. 각 장면마다 “왜 문제인지”와 “어떻게 바꾸면 되는지”를 코드로 직접 보여 드리겠습니다.
장면 1. “동작은 하는데 다시 보니 모르겠다”
가장 흔한 출발점입니다. 코드를 처음 쓸 때는 머릿속에 맥락이 가득하니 d, n, flag 같은 이름도 충분해 보입니다. 문제는 그 맥락이 며칠이면 증발한다는 점입니다.
// 작성 당시엔 알았지만, 2주 뒤엔 미궁
let d = 30;
if (flag) process(n);
여기서 d가 할인율인지 경과일인지, flag가 무엇을 가리키는지는 코드만 봐서는 알 수 없습니다. 이름에 의도를 담으면 주석 없이도 의미가 살아납니다.
let discountRate = 30;
if (isPremiumUser) sendNotification(unreadCount);
핵심 교훈은 단순합니다. 이름은 “지금의 나”가 아니라 “3주 뒤의 나”와 동료를 위해 짓는 것입니다.
장면 2. “이 함수, 이름만 봐선 뭘 하는지 모르겠다”
함수 이름이 명사로만 되어 있거나 너무 추상적이면, 호출하는 쪽에서 매번 함수 내부를 열어 봐야 합니다. 함수는 동작을 하므로 이름도 동사로 시작하는 것이 자연스럽습니다.
같은 동작이라도 어떤 동사를 쓰느냐에 따라 의미가 더 분명해집니다. 아래 표는 상황별로 자주 쓰이는 접두어를 정리한 것입니다.
| 함수가 하는 일 | 권장 시작 동사 | 예시 |
|---|---|---|
| 값을 가져옴 | get / fetch | getUserProfile |
| 참/거짓 판단 | is / has / can | hasUnreadMessage |
| 새로 만듦 | create / build | createOrder |
| 형태를 바꿈 | to / parse / format | formatCurrency |
| 제거함 | remove / delete | removeSession |
특히 참과 거짓을 돌려주는 함수에 is, has, can을 붙이면 if (hasUnreadMessage)처럼 조건문이 영어 문장처럼 읽힙니다. 읽는 사람이 추측할 필요가 사라집니다.
장면 3. “한 파일은 camelCase, 옆 파일은 snake_case”
협업을 시작하면 표기법이 뒤섞인 코드를 만나게 됩니다. camelCase와 snake_case 중 무엇이 옳은가는 사실 중요하지 않습니다. 진짜 중요한 것은 한 프로젝트 안에서 하나로 통일되어 있는가입니다.
| 표기법 | 형태 | 흔히 쓰는 곳 |
|---|---|---|
| camelCase | userName | JavaScript·Java 변수/함수 |
| PascalCase | OrderService | 클래스, 컴포넌트 |
| snake_case | user_name | Python 변수/함수 |
| UPPER_SNAKE | MAX_RETRY | 상수 |
새 팀에 합류했다면 나의 취향을 적용하기 전에 기존 코드가 어떤 규칙을 쓰는지부터 파악하시기 바랍니다. 컨벤션은 옳고 그름의 문제가 아니라 약속의 문제입니다.
장면 4. “chat_roomMessage 같은 혼합형을 발견했다”
실무에서 종종 chat_roomMessage처럼 snake_case와 camelCase가 한 이름에 뒤섞인 혼합형 네이밍을 만나게 됩니다. 보기에 거슬리고, 손이 근질거립니다. 바로 이 지점에서 초급 개발자가 갈림길에 섭니다.
가장 위험한 선택은 “눈에 띈 김에 내가 본 것만 살짝 고치는” 것입니다. 직접 겪어 보니, 일부만 바꾸면 같은 개념이 두 가지 이름으로 갈라져 검색조차 안 되고, 일관성은 고치기 전보다 오히려 더 무너집니다.
현장에서 얻은 원칙 혼합형 네이밍을 봤다면 선택지는 두 가지뿐입니다. ① 그 프로젝트가 따르는 기존 규칙을 그대로 따라간다 (설령 혼합형이라도). ② 정 바꾸겠다면, 팀과 합의한 뒤 전체를 다 바꿀 각오로 일괄 변경한다. 개인 취향으로 일부만 손대는 절충안이 가장 나쁜 결과를 부릅니다.
잘못된 컨벤션이라도 일관된 코드가, 일관성이 깨진 코드보다 읽기 쉽습니다. 통일할 자신이 없다면 차라리 기존 패턴을 존중하는 편이 코드베이스 건강에 이롭습니다.
장면 5. “이름은 길어졌는데 정작 의미는 흐려졌다”
이름을 신경 쓰기 시작하면 반대 방향으로 과해지기도 합니다. 타입을 이름에 박아 넣거나, 맥락을 중복해서 장황해지는 경우입니다.
// 과한 예 — 타입과 맥락 중복
let userNameString;
class User { getUserUserEmail() {} }
// 적절한 예
let userName;
class User { getEmail() {} }
타입을 이름에 넣으면 나중에 타입이 바뀔 때 이름이 거짓말을 하게 됩니다. 또 User 클래스 안이라면 맥락이 이미 user이므로 메서드까지 user를 반복할 필요가 없습니다. 길이가 아니라 명확함이 목표라는 점을 기억하시기 바랍니다.
한눈에 보는 네이밍 자가 점검
작성한 코드를 커밋하기 전, 아래 질문을 스스로 던져 보시기 바랍니다.
- 이 이름을 소리 내어 동료에게 말할 수 있는가
- 주석 없이 이름만으로 의도가 전달되는가
- 함수라면 동사로, 불리언이라면 is/has/can으로 시작하는가
- 프로젝트의 기존 표기법과 일치하는가
- 타입이나 불필요한 맥락을 중복으로 넣지 않았는가
다섯 가지 중 하나라도 걸린다면 이름을 다시 들여다볼 차례입니다.
자주 묻는 질문 (FAQ)
Q1. 반복문의 i, j도 나쁜 이름인가요?
짧고 단순한 반복문에서는 관습적으로 허용됩니다. 다만 중첩이 깊거나 반복문이 길어지면 rowIndex처럼 의미를 담은 이름으로 바꾸는 편이 안전합니다.
Q2. 혼합형 네이밍, 결국 어떻게 하라는 건가요?
기존 규칙을 그대로 따르거나, 팀 합의 후 전체를 일괄 변경하거나 둘 중 하나입니다. 혼자 일부만 고치는 것은 피하시기 바랍니다.
Q3. 변수 이름은 무조건 영어로 써야 하나요?
오픈소스와 대부분의 협업 환경이 영어를 표준으로 삼습니다. 번역 도구를 써서라도 영어로 작성하는 습관을 들이는 편이 장기적으로 유리합니다.
Q4. 좋은 이름을 빨리 떠올리는 방법이 있나요?
“이 값이 무엇인지 한 문장으로 설명”한 뒤, 그 문장의 핵심 명사·동사를 이름으로 압축하는 연습이 효과적입니다. 처음엔 느려도 금세 빨라집니다.
마무리
다섯 개의 장면을 따라오며 한 가지 흐름을 느끼셨을 것입니다. 클린 코드 네이밍 규칙은 외워야 할 법칙이 아니라, 읽는 사람을 배려하는 태도에 가깝습니다.
특히 혼합형 네이밍 같은 회색 지대에서는 “기존 규칙을 따르거나, 전체를 바꿀 각오로 통일하거나”라는 두 갈래만 기억하시면 됩니다. 어설픈 부분 수정은 결국 미래의 누군가에게 숙제를 떠넘기는 일입니다.
다음 커밋부터, 변수 하나를 지을 때 3초만 더 고민해 보시기 바랍니다. 그 3초가 쌓여 코드의 품격을 만듭니다.
별도 스타일 가이드가 없다면 Google 엔지니어링 스타일 가이드 를 참고해보세요.
핵심 요약
- 이름은 3주 뒤의 나와 동료를 위해 의도를 담아 짓습니다
- 함수는 동사로, 불리언은 is/has/can으로 시작합니다
- 표기법은 옳고 그름이 아니라 프로젝트 내 통일의 문제입니다
- 혼합형 네이밍은 기존 규칙 유지 또는 전체 일괄 변경 — 부분 수정은 금물입니다