AI랑 같이하는 코딩

1. 주제 소개

코드가 길지 않은데도 이해하기 어려운 경우가 있습니다. 원인을 따라가 보면 대부분 변수명에서 막힙니다. `a`, `data`, `temp`, `value2`, `resultFinal` 같은 이름은 작성자 머릿속에서는 의미가 있지만, 며칠 뒤 본인이나 팀원이 보면 문맥을 다시 해석해야 합니다. 즉 코드가 동작하더라도 읽는 비용이 크게 증가합니다. 초보 단계에서는 기능 완성에 집중하다 보니 변수명을 대충 정하기 쉽지만, 실제 유지보수에서는 이 작은 습관이 가장 큰 시간을 잡아먹습니다.

이번 글에서는 "이름이 애매한 변수명"을 어떻게 읽기 좋은 형태로 바꿀지 Before & After 관점으로 다룹니다. 중요한 기준은 어렵지 않습니다. 변수명만 읽어도 값의 정체와 용도, 단위, 상태가 떠오르는가를 확인하면 됩니다. 이 기준을 통과하면 디버깅 속도, 리뷰 품질, 협업 효율이 동시에 좋아집니다.

2. 핵심 내용

좋은 변수명은 길이가 아니라 정보량으로 판단해야 합니다. 짧아도 명확하면 좋고, 조금 길어도 의미가 분명하면 더 좋습니다. 예를 들어 `d`보다 `discountRate`, `n`보다 `userCount`, `list`보다 `pendingOrders`가 훨씬 읽기 쉽습니다. 특히 컬렉션 변수는 복수형을 사용하고, 불리언은 `is`, `has`, `can`, `should`로 시작하면 조건문의 의도가 또렷해집니다. `active`보다 `isActive`, `check`보다 `hasPermission`이 좋은 이유입니다.

두 번째 기준은 시간과 상태를 드러내는 것입니다. 같은 데이터라도 시점이 다르면 이름을 분리해야 혼동이 줄어듭니다. `user` 하나로 모든 단계를 처리하기보다 `rawUser`, `validatedUser`, `savedUser`처럼 상태를 드러내면 디버깅 포인트가 명확해집니다. 세 번째 기준은 단위를 포함하는 습관입니다. 금액, 시간, 비율처럼 해석이 갈리는 값은 `timeoutMs`, `priceKrw`, `successRate`처럼 단위를 붙이는 것이 안전합니다.

마지막으로 "너무 일반적인 이름"을 경계해야 합니다. `data`, `item`, `obj` 자체가 나쁜 것은 아니지만 범위가 넓은 파일에서 계속 등장하면 의미 충돌이 생깁니다. 이때는 해당 변수의 역할을 한 단어 더 추가해 `userProfileData`, `cartItem`, `requestPayload`처럼 구체화하면 코드 독해 속도가 빠르게 올라갑니다.

3. 적용 방법

실제 프로젝트에서는 한 번에 전부 바꾸지 말고 화면 단위나 모듈 단위로 진행하세요. 먼저 함수 안에서 "읽을 때 멈칫하는 이름"을 표시하고, 그 변수가 무엇을 담는지 한 문장으로 설명해 봅니다. 설명 문장을 그대로 변수명으로 압축하면 대부분 좋은 이름 후보가 나옵니다. 이후 이름 변경은 IDE 리네임 기능을 사용해 참조를 함께 바꾸고, 테스트나 실행으로 동작을 확인합니다. 이 과정을 30분 단위로 반복하면 품질과 안정성을 함께 가져갈 수 있습니다.

Before 코드에서는 변수명을 이해하기 위해 위아래 코드를 계속 왕복하게 됩니다. After 코드에서는 변수명 자체가 설명 역할을 하므로 주석 의존도가 줄고, 리뷰어도 로직 문제에 집중할 수 있습니다. 변수명을 바꾸는 작업은 작아 보이지만, 실제로는 버그를 줄이는 구조 개선입니다. 특히 신규 팀원이 합류했을 때 온보딩 시간을 단축해 준다는 점에서 투자 대비 효과가 큽니다.

4. 정리

애매한 변수명은 코드 품질을 조용히 떨어뜨리는 대표 원인입니다. 반대로 명확한 이름은 코드의 의도를 드러내는 가장 저렴한 문서입니다. 오늘 당장 적용할 수 있는 기준은 세 가지입니다. 역할이 보이는 이름을 쓸 것, 상태와 단위를 드러낼 것, 불리언은 질문형으로 읽히게 만들 것. 이 세 가지만 지켜도 "코드를 해석하는 시간"이 눈에 띄게 줄어듭니다. 좋은 변수명은 센스가 아니라 훈련의 결과이며, 작은 파일에서부터 반복하면 누구나 개선할 수 있습니다.

5. 자주 묻는 질문