깔끔한 코드를 위한 좋은 변수명, 함수명 짓기

프로그램개발

깔끔한 코드를 위한 좋은 변수명, 함수명 짓기

이번 글은 변수명과 함수명을 명확하게 짓는 방법과 그 중요성에 대해 다룹니다. 코드를 작성하면서 겪을 수 있는 혼동을 줄이고, 유지 보수와 확장성을 높이는 데 도움이 될 것입니다.

개발자로서 매일같이 마주하는 과제 중 하나는 코드 가독성을 높이는 일입니다. 코드는 단순히 컴퓨터에게 명령을 내리는 수단임과 동시에, 여러 사람이 함께 작업하거나 미래의 자신이 다시 확인할 수도 있는 '설계 문서' 역할도 합니다. 이때, 가독성을 결정하는 가장 중요한 요소 중 하나가 바로 변수명과 함수명입니다.

일단 코드를 작성할 때는 일이 급해서, 혹은 단순 반복 업무처럼 느껴져서 변수나 함수의 이름을 되는 대로 지어버리는 경우가 많습니다. 하지만 이렇게 급하게 지은 이름들은 나중에 코드를 다시 확인할 때 극심한 혼란을 초래합니다. 따라서 조금의 시간을 들여서라도, 코드에서 쓰이는 주요 식별자(identifier)들의 이름을 깔끔하고 직관적으로 짓는 것이 장기적으로 큰 도움이 됩니다.

이번 글에서는 깨끗하고 유지 보수하기 좋은 코드를 위해 좋은 변수명, 함수명을 짓는 실질적인 방법과 주의할 점을 살펴보겠습니다.

1. 왜 좋은 이름이 중요한가?

• 가독성 향상
  코드가 길어지고 복잡해질수록 가독성이 떨어지기 쉬운데, 적절한 이름을 통해 현재 코드가 무엇을 하는지, 어떤 데이터가 오가는지 빠르게 파악할 수 있습니다. 이는 협업 시에 특히 중요합니다. 새로운 팀원이 합류하거나, 과거 코드를 새로 리뷰해야 하는 상황에서 이름이 직관적이라면 생산성이 크게 향상됩니다.
• 의도 전달
  이름을 통해 이 변수가 어떤 용도로 사용되는지, 함수가 어떤 역할을 수행하는지를 명시적으로 나타낼 수 있습니다. 예를 들어 단순히 count라고만 하면 무엇을 세는지 모호하지만, userCount 혹은 activeUserCount로 명확히 해준다면 코드를 읽는 사람은 바로 그 의도를 파악할 수 있습니다.
• 오류 예방
  좋은 이름은 의도를 명확히 드러내기 때문에, 잘못된 함수 호출이나 변수 사용을 방지할 수 있습니다. 반대로 중의적이거나 혼동이 심한 이름을 쓰면, 사용자가 잘못된 방식으로 변수나 함수를 호출할 가능성이 높아집니다.
• 유지 보수 비용 절감
  유지 보수를 하다 보면, 처음 작성했던 코드를 훨씬 나중에 다시 보게 될 때가 있습니다. 이름만 잘 지어도 “이게 무슨 역할을 하는 거였지?” 하는 고민에 빠지는 시간을 크게 줄일 수 있습니다. 결과적으로 유지 보수와 리팩터링 비용이 낮아집니다.

2. 변수명을 짓는 기본 원칙

• 의미가 분명해야 한다
  변수명은 그 변수에 담긴 값이 무엇인지, 어떤 용도로 쓰이는지를 명확히 나타내야 합니다. 예를 들어, 남은 시간에 대한 정보를 담고 싶다면 remainingTime이라고 지어주면 됩니다. 더 구체적으로 단위를 포함해 remainingTimeInSeconds라고 작성할 수도 있습니다.
• 줄임말 지양
  '짧은 이름이 멋있다'라는 생각으로 rmnTm 같이 줄여서 표기하면, 다른 개발자(혹은 나중의 자신)에게 큰 혼란을 야기할 수 있습니다. 최소한 해당 프로젝트에서 자주 쓰이거나 모두가 인지하는 약어가 아니라면 줄임말을 피하고, 가급적 정확한 의미를 담도록 합시다.
• 의미 없는 일반 단어 지양
  data, info, tmp 같은 포괄적이거나 임시를 의미하는 단어를 변수를 가리키는 이름으로 자주 사용하는 경우가 있습니다. 이처럼 광범위한 의미의 단어는 변수가 실제로 어떤 역할을 하는지를 전혀 드러내지 못합니다. userData, updatedUserInfo, tempFilePath처럼 맥락을 추가하는 것이 좋습니다.
• 일관성 유지
  같은 유형, 같은 맥락의 변수들은 비슷한 형식의 이름 규칙을 유지하는 것이 좋습니다. 예컨대 startDate와 endDate라는 변수가 있다면, 시간을 의미하는 변수는 모두 비슷한 패턴(xxxDate)으로 작성해 일관성을 주는 식입니다.
• 코딩 컨벤션(네이밍 컨벤션) 활용
  언어나 프레임워크에 따라 권장되는 네이밍 컨벤션이 있습니다. 예를 들어, 파이썬에서는 snake_case를 변수명으로, 자바스크립트나 자바에서는 camelCase를 쓰는 것이 일반적입니다. 프로젝트 내에서 통일성이 깨지지 않도록, 팀 또는 개인이 정한 컨벤션을 철저히 지키도록 합시다.

3. 함수명을 짓는 기본 원칙

• 동사 + 목적어 구조 사용
  함수는 특정 동작을 수행하는 '행위자'입니다. 따라서 getUserInfo, calculateTotalPrice와 같이 동사형으로 시작하고, 필요한 대상(목적어)을 뒤에 덧붙여주는 식으로 이름을 짓는 것이 일반적입니다.
• 함수의 책임(의도)이 드러나야 한다
  함수가 어떤 일을 하는지 알 수 있도록 이름을 짓는 것이 중요합니다. 하나의 함수가 여러 일을 처리하지 않도록, 되도록 한 가지 책임만 지도록 설계한 뒤 이름도 그 역할에 맞춰 짓는 것이 좋습니다. 예컨대 saveUserDataAndSendEmail처럼 너무 많은 일을 연달아 의미하는 함수명은, 책임 분리가 덜 된 함수를 암시하기도 합니다.
• 부정형이나 모호한 단어 지양
  checkError처럼 모호한 단어가 들어간 함수는 의도 파악이 어렵습니다. 해당 함수가 에러를 '확인'하고 결과를 리턴하는지, 에러가 있으면 'throw'하는지, 에러를 '로깅'하는지 불분명할 수 있습니다. validateInput, throwIfInvalidData처럼 목적이나 동작이 확실히 드러나는 동사를 사용하면 가독성이 높아집니다.
• 길이에 대한 고민
  너무 긴 이름도 가독성을 해칠 수 있습니다. 다만, 이름이 너무 짧아 의도가 모호해지는 것보다는 차라리 길어도 의미가 분명한 쪽이 낫습니다. 예를 들어 validatePaymentMethodAndReturnResultIfValid처럼 매우 구체적인 이름을 붙였는데, 읽는 사람이 한눈에 기능을 파악할 수 있다면 오히려 효율적일 수 있습니다.
• 일관된 시그니처와 네이밍
  여러 함수가 연관되어 있을 때는 비슷한 형식으로 이름을 지어주는 것이 좋습니다. 예를 들어, fetchData, updateData, deleteData, createData 등으로 같은 프로젝트 내에서의 일관성을 유지하면 이해가 훨씬 쉬워집니다.

4. 자주 하는 실수와 주의할 점

• 약어 남용
  앞서 언급했듯이, 심하게 축약된 이름은 한 번 이해한 뒤에도 곧 잊어버리기 쉽습니다. 특히 팀 단위로 작업할 경우, 약어 사용이 심해지면 '외계어'가 난무하는 코드가 되어버립니다.
• 헷갈리는 이름 재활용
  이미 다른 의미로 사용되고 있는 단어나 변수명을 다시 쓰면 혼란을 일으킵니다. 예컨대 count라는 이름의 변수가 여러 곳에서 다른 용도로 쓰인다면, 코드를 읽는 사람들이 헷갈릴 수밖에 없습니다.
• 의미 없는 접두어/접미어 사용
  개인 습관으로 변수나 함수 앞에 특정 문자를 붙이는 경우가 있는데, 예를 들어 모든 변수를 v_로 시작한다거나 함수를 fn_으로 시작하는 식입니다. 옛날 헝가리안 표기법(Hungarian notation)과 같은 방식을 아직도 쓰는 경우가 있지만, 현대 언어 환경에서는 IDE나 에디터가 충분히 타입 정보를 제공하므로 크게 유의미하지 않은 경우가 많습니다.
• 함수명과 변수명을 혼동
  함수명을 user처럼 명사로만 짓거나, 변수를 getUser처럼 동사로 지어버리면 유지 보수 시 헷갈릴 가능성이 큽니다. “이게 함수였나? 변수였나?” 하는 고민이 들지 않도록, 의도한 역할에 맞게 명사, 동사 형태를 철저히 구분하세요.

5. 코드 예시를 통한 비교

// ❌ 나쁜 예시
function fn(dt) {
  const cnt = dt.length;
  dt.forEach((v) => {
    console.log(v);
  });
  return cnt;
}

// ✅ 좋은 예시
function printAndCountItems(items) {
  const itemCount = items.length;
  items.forEach((item) => {
    console.log(item);
  });
  return itemCount;
}

위 예시에서 fn, dt, cnt, v와 같이 모호하고 축약된 이름을 사용하면 코드 가독성이 떨어집니다. 반면 printAndCountItems, items, itemCount, item 등으로 명확하게 바꿔줌으로써 함수가 어떤 일을 하는지 쉽게 알 수 있고, 유지 보수도 훨씬 편리해집니다.

6. 결론 및 요약

의도가 드러나는 이름: 변수명이나 함수명만 봐도 그 의도를 알 수 있어야 합니다.

명확하고 구체적인 단어 선택: 줄임말이나 불분명한 약어를 최대한 지양하고, 의미가 분명한 단어를 사용합니다.

일관된 네이밍 컨벤션: 프로젝트 전체 혹은 팀 내에서 합의한 컨벤션을 준수하여, 코드가 일관성을 가지도록 합니다.

함수명은 동사, 변수명은 명사: 역할에 따라 네이밍 형태를 달리하여 헷갈리지 않도록 합시다.

변수명과 함수명 짓기는 사소해 보이지만, 코드 전반의 가독성과 유지 보수성에 큰 영향을 미치는 중요한 요소입니다. 한두 번 코드를 짤 때는 잘 느끼지 못하더라도, 프로젝트 규모가 커지고 여러 사람이 협업할수록 그 가치가 두드러집니다. 다소 귀찮더라도, 잠시 시간을 내어 직관적이고 깔끔한 이름을 고민해 보는 습관을 들이길 바랍니다.

좋은 이름은 좋은 문서가 된다.
코드를 다시 읽을 때, 별도의 주석 없이도 이름만 보고도 '아, 이게 이런 일을 하는구나'를 파악할 수 있는 코드가 궁극적으로 유지 보수가 용이하고 오류가 적은 코드입니다.

지금까지 소개한 원칙과 주의사항을 실천해보면, 누가 봐도 쉽게 이해할 수 있는 '깔끔한 코드'에 한 발 더 다가갈 수 있을 것입니다. 단순히 규칙을 강제한다기보다는, 협업의 효율과 미래의 편의를 위해 모두가 함께 노력하는 문화가 자리 잡기를 바랍니다.

프로그램개발 관련 게시물 바로가기