개발 생산성 높이는 코드 네이밍 비법 5가지

안녕하세요. 인포그랩 프로덕트 팀에서 백엔드 엔지니어로 일하는 Andy입니다. 오늘은 제가 평소 코드를 작성할 때 중요하게 생각하는 주제인 네이밍(naming: 이름짓기)을 이야기해 보려고 합니다.

출처=픽사베이

개발자는 일반적으로 클래스, 변수, 함수 등을 네이밍하는데요. 네이밍은 코드의 가독성, 유지보수성, 협업 효율성에 큰 영향을 미칩니다. 예를 들어, 변수나 함수 이름을 실제 의미와 일치하도록 짓고, 이름만 봐도 내용을 즉시 이해하도록 지으면 개발팀이 빠르고 정확하게 소통할 수 있고요. 이는 개발 생산성을 높여줍니다.

이에 많은 개발자가 항상 고민하면서 클래스, 변수, 함수 등을 네이밍하죠. 저도 코드 작성 과정에서 네이밍할 때, ‘이 이름이 정말 직관적인가?’라고 자주 생각합니다. 특히 ‘다른 팀원들이 이름을 보고도 코드 역할을 바로 알도록 네이밍하는 방법이 늘 고민인데요. 이러한 이유로 평소 네이밍을 잘하는 방법을 조사하고 연구하죠. 이 글에서는 제가 학습한 내용을 토대로 “개발 생산성을 높이는 가독성 좋은 코드 네이밍 비법 5가지”를 소개하겠습니다.

네이밍 잘해야 하는 이유

개발자는 코드를 작성할 때 로직을 잘 짜야 하죠. 그러나 다른 팀원들이 코드를 직관적으로 정확히 이해하도록 네이밍을 잘하는 것도 중요합니다. 아래 예제와 함께 그 이유를 살펴보겠습니다.

function doStuff(data: any) {
  const result = [];
  for (const item of data) {
    if (item.isActive) {
      result.push(item);
    }
  }
  return result;
}

위 예제에서 doStuff라는 이름만 보면, 이 함수 역할을 바로 이해하기 어렵습니다. Stuff라는 단어가 추상적이라 구체적인 의미가 바로 전달되지 않고요. 이에 함수 내부 로직까지 샅샅이 살펴보게 되죠. 함수 역할을 정확히 파악하는 데 시간이 걸립니다.

또 이 예제에서는 함수 입력 인자와 내부 변수가 data, item, result라는 단어로 쓰였는데요. 이 또한 의미를 즉시 인지하기에는 일반적이고 모호한 단어입니다. 누군가는 생각 회로를 여러 번 돌려야 내용을 이해할 수도 있습니다.

다른 팀원들이 위 예제를 보고 doStuff 함수를 빠르게 사용하고 수정할 수 있을까요? 함수 역할을 정확히 파악하지 못해 부작용이 생기지는 않을까요? 그렇다면 이 문제를 어떻게 예방해야 할까요? 저는 다음 5가지 네이밍 방법을 제안합니다.

1. 클래스/변수/함수 대상과 행위 나타내기
2. 명사와 동사 활용하기
3. 시제와 동사 형태 구체화하기
4. 필수 접두사/접미사만 사용하기
5. 불명확한 약어 대신 명확한 본딧말 쓰기

비법 1. 클래스/변수/함수 대상과 행위 표현

이름에 ‘클래스/변수/함수 등의 대상과 행위’를 담으면 가독성이 좋아집니다. 이로써 대상의 책임 범위, 대상을 사용하는 코드 역할을 정확히 드러낼 수 있죠.

반면에 ‘클래스/변수/함수 등이 언제, 어디서, 어떻게 사용되는지’를 이름에 넣으면, ‘클래스/변수/함수 등의 역할’이 드러나지 않아 내용을 바로 이해하기 어렵습니다.

함수 이름과 변수 이름의 잘못된 예와 올바른 예를 살펴보겠습니다.

잘못된 예

• handleButtonClickInProfileScreen: 프로필 화면에서 버튼을 클릭할 때 호출되는 함수

  이름에 ‘함수가 어디서(프로필 화면), 언제(버튼 클릭 시) 사용되는지’만 나오는데요. 함수가 호출될 때 수행하는 역할을 알 수 없습니다.

• isNavigatedFromHomeScreen: 홈 화면에서 이동할 때 true가 되는 변숫값

  이 이름도 ‘변숫값이 어디서(홈 화면에서 이동) 사용되는지’만 나와 값의 의미를 정확히 파악하기 어렵습니다.

올바른 예

• ProductListProvider: 상품 리스트를 제공하는 클래스

  이름에 ‘상품을 대상으로 제공되는 클래스’라고 클래스의 대상과 역할을 분명히 표현했습니다.

• showErrorModal: 에러 모달 창을 보여주는 함수

  ‘’에러’라는 대상에 모달을 보여주는 함수’라고 함수의 대상과 역할을 이름에 구체적으로 나타냈습니다.

비법 2. 명사와 동사 활용

명사/명사구, 동사를 이름에 사용해도 가독성 향상에 도움이 됩니다. 유형별 사용 사례는 다음과 같습니다.

명사/명사구

명사/명사구는 클래스, 인터페이스, 변수, 인수, 객체를 반환하는 함수 이름에 활용합니다. 네이밍 대상을 이름 마지막에 두면 함수 의미를 효과적으로 전달할 수 있죠.

예를 들어, ‘버튼의 넓이’를 나타내는 변수를 네이밍해 봅시다. 이 변수에서 가장 중요한 단어는 넓이입니다. 따라서 변수 이름은 buttonWidth가 적합합니다. 만약 widthButton이라고 네이밍하면, 다음 문제가 생길 수 있는데요.

• 어순에 따라 “넓이 버튼”으로 직역돼 변수 속성이 모호해집니다.
• “넓이 버튼”은 ‘넓이를 조절하는 버튼’으로 오해될 수 있습니다.

또 다른 예로, ‘모바일 모드일 때 사용하는 버튼의 넓이’를 나타내는 변수를 네이밍해 보죠. 이 변수 이름에는 ‘모바일 모드’라는 정보가 들어가야 합니다.

전치사를 넣어 buttonWidthInMobileMode라고 네이밍해 봅시다. 이름이 길지만 전치사가 buttonWidth와 MobileMode라는 단어를 효과적으로 구분해 줍니다. 이로써 변수가 잘 이해되고, ‘이 변수가 어디에 쓰이는지’ 명확히 알 수 있죠.

전치사를 활용한 네이밍은 indexOf(value), maxValueIn(array) 같은 함수에도 사용되는데요. 전치사를 넣으니까 ‘함수/변수가 어디에 쓰이고, 어떤 맥락에 사용되는지’ 바로 이해할 수 있습니다.

동사

동사는 메서드, 함수 이름에 사용합니다. 이는 동작 내용을 직관적으로 표현해 함수가 수행할 작업을 분명하게 보여줍니다. 특히 동사 원형을 함수 이름 맨 앞에 두면 함수 의미를 정확하게 바로 이해할 수 있죠.

예를 들어, “상품을 구매하는” 함수를 네이밍해 봅시다. productPurchase라고 이름을 지으면, 어순을 고려할 때 이를 ‘상품을 구매’한 게 아닌 ‘구매된 상품’으로 오해할 수 있습니다. 그러나 purchaseProduct라고 네이밍하면, 어순에 따라 “상품을 구매하다”라는 의미가 올바로 전달됩니다.

비법 3. 시제와 동사 형태 구체화

이름에 시제와 동사 형태를 구체적으로 나타내도 가독성이 한층 더 높아집니다.

예를 들어, ‘사용자 상품 구매 여부의 boolean 값’을 저장하는 변수를 네이밍해 봅시다. 이때 purchaseFlag라고 네이밍하면, 개발자 동료가 이렇게 오해할 수 있습니다.

• true면 ‘사용자가 구매 가능하다’는 의미인가? 아니면 ‘이미 구매했다’는 의미인가?

이 변수 이름을 isPurchased로 변경하면, 이러한 문제를 막을 수 있는데요. Purchase 앞에 is, 뒤에 ed가 붙어 시제(현재)와 동사 형태(수동태)를 구체화해 의미를 더 명료하게 드러내죠. 그 결과, 이름만 봐도 ‘이 변수는 true일 때, ‘이미 구매했다’는 의미구나’라고 정확하게 해석할 수 있습니다.

또 다른 예로, ‘사용자의 프로필 업데이트 여부의 boolean 값’을 저장하는 변수를 네이밍해봅시다. 이를 updateProfileFlag로 네이밍하면, 다음 혼란이 생길 수 있는데요.

• ‘업데이트가 가능하다’는 의미인가?
• ‘이미 업데이트했다’는 건가?
• ‘업데이트 중’이라는 의미인가?

이 변수 이름을 isProfileUpdated로 변경하면, 이러한 문제를 방지할 수 있습니다. Profile 앞에 is가, Update 뒤에 ed가 붙어 시제(현재)와 동사 형태(수동태)를 구체화했고요. 이제 이름만 봐도 ‘이 변수가 true면, ‘사용자의 프로필이 업데이트됐다’는 의미구나’라고 명확히 알 수 있죠.

비법 4. 필수 접두사/접미사만 사용

필요한 접두사나 접미사만 이름에 활용하는 것도 가독성 개선에 필수입니다.

개발자는 특정 패턴이나 컨벤션을 따르려고 불필요한 접두사나 접미사를 이름에 붙일 때가 있는데요. 그 결과, 클래스/변수/함수 등의 책임과 역할이 이름에 모호하고요. 이름에 정보까지 중복돼 코드가 장황해집니다.

let userDtoData;  // 'Dto'와 'Data' 의미가 중복되며, 두 단어 모두 접미사에 쓸 필요가 없음
let isFlagEnabled; // 'Flag'는 필수적이지 않은 접미사임
let doProcessAction(); // 'do'와 'Action' 의미는 중복되며, 둘 다 있을 필요가 없음

위 변수 이름을 살펴보죠. 모든 변수 이름에 중복(Dto, Data, do, Action)되거나 필수적이지 않은 접미사(Flag)가 들어갔는데요. 같은 정보가 변수 이름 안에서 반복돼 보는 사람이 피로합니다.

let userDto;  // 'Dto'만으로 '데이터 전송 객체임'을 충분히 표현함
let isEnabled;  // 'boolean 값임'을 명확하게 표현함
let process();  // 'process'만으로 동작을 충분히 설명함

이 변수 이름을 위와 같이 개선할 수 있는데요. 중복되는 단어(Data, do, Action)와 필수적이지 않은 접미사(Flag)를 없앴습니다. 이로써 변수 의미가 간결하고 분명하게 전달되죠.

비법 5. 약어 < 본딧말

의미가 불명확한 약어 대신 의미가 명확한 본딧말(줄이지 않은 본래 말)을 사용해도 가독성이 좋아집니다.

코드에서는 효율적으로 소통하기 위해 약어를 자주 활용하죠. 그러나 약어 의미가 분명하게 전달되지 않으면 혼란스럽습니다. 특히 협업하는 개발자가 약어 뜻을 바로 이해하지 못하면, 코드의 가독성이 떨어지고 유지보수성도 낮아지죠. 약어는 협업에서 정확한 소통을 방해할 수 있기에 의미가 명확한 본딧말을 사용하면 좋습니다.

let usrAddr;  // 전체 변수 이름은 사용자 주소를 나타내지만, 'usr' 의미가 불명확함
let cfg;      // 'cfg'가 '설정(configuration)'의 전체 영문 표기와 비슷해 보이지만 확실하지 않음
let tempVal;  // 'temp'가 '임시(temporary)'인지 '온도(temperature)인지' 불명확함

위 변수 이름에는 다양한 약어가 쓰였는데요. 약어 의미가 명료하게 와닿지 않습니다. usr가 ‘어떤 단어의 약어인지’ 단번에 떠오르지 않고요. 누군가는 cfg만 보고 ‘이 약어가 ‘설정(configuration)’을 뜻한다’는 걸 바로 깨닫지 못할 수 있습니다. temp도 다양한 단어로 받아들일 수 있고요.

let userAddress;    // 전체 변수 이름이 '사용자 주소'를 뜻하는 데 의심할 여지가 없음
let configuration;  // 전체 변수 이름이 '설정'을 의미한다는 걸 명확하게 전달함
let temporaryValue; // 변수가 '임시 값'임이 분명해짐

이러한 약어를 위와 같이 모두 본딧말로 바꿨습니다. 단어를 줄이지 않고 그대로 이름에 쓰니 의미가 정확하게 전달되고요. 오해 소지가 전혀 없습니다.

마무리

코드 네이밍은 코드 작성을 넘어 개발 협업과 유지 보수를 원활하게 합니다. 이름을 잘 지으면 팀원들이 코드를 쉽게 이해하고 수정할 수 있고요. 이로써 코드 품질과 개발 속도가 높아집니다. 그 결과, 개발 생산성이 전반적으로 향상됩니다. 이 글에서 소개한 가독성 좋은 코드 네이밍 비법이 직관적이고 명확하며, 쉽고 정확하게 이해되는 코드를 작성하는 데 도움이 되길 바랍니다. 긴 글 읽어주셔서 감사합니다.

참고 자료

1. Gervais Yao Amoah, “A Guide to Clean Code: The Power of Good Names”, DEV, 2023.10.21, https://dev.to/gervaisamoah/a-guide-to-clean-code-the-power-of-good-names-3f6i
2. Shahryar Tayeb, “Clean Code: 8 Best Practices For Naming a Variable:, LinkedIn, 2023.11.7, https://www.linkedin.com/pulse/clean-code-8-best-practices-naming-variable-shahryar-tayeb-znhpf/
3. Miguel Loureiro, “Clean code 101 — Meaningful names and functions”, Coding skills, 2015.7.21, https://medium.com/coding-skills/clean-code-101-meaningful-names-and-functions-bf450456d90c
4. 이시가와 무네토시(저), 정기욱(역), “코드 작성 가이드”, 길벗, 2024

DevOps와 GitLab을 효과적으로 도입하는 방법, 지금 인포그랩에 문의하세요.