brunch

You can make anything
by writing

C.S.Lewis

by 승규 Jul 19. 2021

변수명을 잘 짓기 위한 몸부림

클래스, 함수, 변수에 대한 이름 짓기는 개발자들에게는 항상 주된 고민거리이다. 이름을 짓는다는 것은
개발자의 의도를 드러내는 행동이기 때문이고 의도한 바를 다른 사람에게 잘 전달하는 것은
늘 어려운 일이다. 본 문서에서는 이름을 어떻게 지으면 될지 같이 고민해보자.

코드 작성은 무엇을 하기 위한 행위인가?

우리는 코드를 왜 작성하는가? 여러 가지 이유가 있지만, 목표로 하는 기능을 달성하기 위해 코드를 작성한다. 문제는 우리가 만든 코드는 목표를 달성한 후에 다른 이유들로 (스펙의 수정, 일정의 변경, 담당자의 변경) 수정이 될 가능성이 매우 높다는 것이다. 그렇다면 우리는 코드를 작성할 때, 동작 유무만 잘 판단하는 것이 아니라 잘 읽히도록 코드를 작성해야 한다. 잘 읽히도록이라는 것은 어떤 의미일까? 내가 아닌 다른 사람이 코드를 읽고 이해하는데 들어가는 시간을 최소화해야 한다는 것이다. 그러면, 코드를 이해한다는 것은 어떤 의미일까? 그 코드를 자유롭게 수정할 수 있다는 의미가 된다. 따라서 코드 작성의 목표는 원하고자 하는 기능을 수행하면서, 다른 사람이 이해하는데 드는 시간을 최소화하는 데 있다고 할 수 있다.

어떻게 하면 이해하기 쉬운 코드가 되는가?

읽기 좋은 코드가 좋은 코드다 라는 책에서는 가독성 향상에 대해서 다루고 있는데 그 책에서는 이름에 정보를 담아내라고 이야기하고 있다. 가독성 향상은 좋은 이름을 짓고, 좋은 설명을 달고, 코드를 보기 좋게 정렬하는 것을 의미한다. 좋은 이름을 짓는다는 것은 이름에 정보를 담아내는 것을 의미한다. 많은 사람들이 tmp, a, z 같은 의미가 모호한 이름을 사용하는 경우가 많다. 정보를 잘 표현하는 좋은 이름을 담아내야 한다.

특정한 단어 고르기

get_something은 굉장히 많이 사용되는 함수명이다.

get 은 대부분의 경우에 괜찮은 이름이지만, 네트워크를 통해서 가져오는 경우는 fetch나 download를 사용하는 것이 좋다. 영어단어를 보면 비슷하지만, 뉘앙스가 다른 여러 개의 단어가 있는 경우가 많다. 의미를 적절히 잘 살려서 지으면 좋을 것이다.

아래는 영어 유의어 사전의 링크이다. 변수명을 지을 때 참고하면 좋겠다.

Synonyms and Antonyms of Words | Thesaurus.com

또한 꼭 필요한 경우가 아니라면 너무 어려운 단어는 피하는 것이 좋을 것이다. {ㅁㅁ} 검색 기능인데 inquiry라는 단어가 있어서 의도치 않게 영어공부를 했던 기억이 있다. 지금 생각하면 작성자가 search라는 이름으로 해줬으면 더 좋았을 것 같다.

의미 없는 단어 피하기

개발할 때 tmp, result 등 너무나 보편적인 의미를 지니는 이름을 변수에 짓는 경우가 많이 있다. 해당 변수의 역할을 알려면 이름만으로는 알 수 없고 전후 상황(콘텍스트)을 다시 살펴봐야 하기에 가능하면 정보를 더 담은 이름이 좋겠다. 그렇지만, 정말로 tmp가 임시로 값을 담는 역할을 하는 것이라면 올바른 코드라고 할 수 있겠다. 아래와 같은 경우이다.

if right < left:
    tmp = right
    right = left
    left = tmp

이름은 얼마나 길어야 되는가?

프로그래머들에게는 이름이 너무 길면 안 된다는 암묵적인 룰이 있는 것 같다. 최근에는 인텔리센스(이름을 일부만 쳐도 찾아주는 IDE기능)가 좋아져서 변수명이 길어도 IDE를 사용해서 대부분 코딩하기 때문에, 변수명이 긴 것이 문제가 된다기보다는 변수가 너무 길어지면 가독성이 좋지 않아 지는 것이 좋지 않다고 생각한다. 그렇기 때문에 가독성을 해치지 않는 선이면 충분히 길어져도 괜찮다고 생각한다. 38자 정도까지는 문제없지 않을까? (그래야 38자 변수 두 개 사이에 = 를 넣어서 할당을 할 수 있으니…) 변수 명의 길이보다는 변수가 충분한 정보를 잘 담고 있으냐가 중요하다.

좁은 범위에서만 사용되는 이름이라면 짧아도 된다고 생각한다. 예를 들어 아래와 같은 경우이다.

if debug:

sl = series_list(**filter)

print(sl)

위의 코드에서 sl은 series_list의 약자이지만, 짧은 범위에서만 사용한다면 무엇인지 바로 알 수 있기 때문에 코드를 이해하는데 문제가 없다.

변수가 어떤 정보를 담아야 하는지에 대해서는 알 로벨 시 Good naming is a process, not a single step의 글이 도움이 될 것 같다. 요약하면 아래와 같다.

알로벨시의 글은 설계 시의 도메인 요소에 대한 이름을 정하는 법이므로 변수에 적용하기에는 다소 과하지만, 이름을 한번 정하고 끝내는 것이 아니라 더 좋은 이름이 생각나면 변경해야 된다는 의미에서는 좋은 것 같아서 담아보았다.

1단계 모름 : 이름을 못 지었음.

2단계 난센스 : 아무 이름이나 넣어서 이름에 의미가 없음

3단계 정직 : 한 가지 역할에 대해서는 알려줌

4단계 정직하고 완전함 : 모든 역할에 대해서 알려줌

5단계 올바름 : 이름이 앞으로 발전할 방향에 대해서도 알려줌. 아키텍처의 전체 맥락 안에서 요소가 가지는 의미가 분명해짐

6단계 의도를 담음 : 역할뿐만 아니라 목적도 설명함. 목적을 설명하려면 역할뿐 아니라 왜 존재해야 되는지도 설명

7단계 도메인 추상화 : 이름이 개별 요소를 추월해 새로운 추상화를 만드는 단계.

예시 )

변수명에 세부 정보를 덧붙여라.

복수개의 요소를 가진 객체의 경우 s를 붙이는 경우가 있다. 이것이 문제가 되지는 않는다. 다만 파이썬의 경우에는 데이터 타입을 넣어주는 것이 더 좋은 경우가 있다. 예를 들어 장고의 queryset은 list처럼 for loop를 돌릴 수 있다. 이런 경우에는 list를 붙이는 것보다는 queryset이라는 클래스 타입을 넣어주는 것이 좋다. 왜냐하면, 파이썬은 자바와 달리 동적으로 타입을 결정하기 때문에 코드를 작성한 사람이 아니라면 변수의 타입을 바로 알기가 쉽지 않다. 이에 이름에 타입을 알 수 있도록 하는 이름을 적어주면 코드를 읽는 사람도 바로 해당 객체의 타입을 알 수 있게 된다.

series_list = Series.objects.all() ( not good )

series_queryset = Series.objects.all() ( good )

오해가 생길 수 있는 이름을 피하자.

사용 중인 코드에 ON_GOING이라는 변수가 있다. 무슨 의미일까? 해석하면 진행 중인 이라는 뜻인데, 실제 코드에서는 유효함이라는 의미로 쓰였다. 이런 일을 피하기 위해서는 가능한 한국어로 영어사전을 찾았을 때 나오는 validity 가 더 나았을 것 같다. 한 가지 더 예시를 보도록 하자. get_duplicate_list라는 함수가 있다. 이름을 보면 무언가의 중복 리스트를 가져오는 함수인 것처럼 보인다. 하지만 실제로 하는 일은 리스트를 넘겨받아서 해당 리스트 안에 중복되어 있는 요소를 가져오는 함수이다. get_duplicates_in_list 로 했으면 조금 더 명확했을 것이다.

이런 부분은 딱히 정해진 룰이 없기 때문에 바로 찾아내기가 쉽지 않다. 팀원들의 힘을 빌려 코드 리뷰를 통해 찾아내도록 하자. 핵심은 내가 지은 이름을 다른 사람들이 다른 의미로 해석할 수 있을까?라는 질문을 스스로 해보아야 한다는 것이다.

불리언 변수에 이름 붙이기

불리언 변수에는 항상 is , has , can, should, use 등을 붙여서 불리언 변수임을 확실히 알 수 있도록 해주자.

SMART 한 방법으로 변수 이름 짓기

SMART는 개발자의 글쓰기라는 책에서 권하는 방법이다. 각 철자 별로 아래와 같다.

easy to Search : 검색하기 쉽고

easy to Mix : 조합하기 쉽고

easy to Agree : 수긍하기 쉽고

easy to Remember : 기억하기 쉽고

easy to Type : 입력하기 쉽고

검색하기 쉽게 이름 짓기

쉽다. 상위 범주의 이름을 앞에 넣으면 된다. 작업자들이 인지를 한다면 상위 범주의 개념을 뒤에 넣는 것도 괜찮다.

안 좋은 예

SERVER_TIMEOUT

NO_RESULT

좋은 예

ERROR_SERVER_TIMEOUT

ERROR_NO_RESULT

조합하기 쉽게 이름 짓기

안 좋은 예

<html>
<head>
<style>
  . big_strong_text {...}
  .sub_title_text {}
  .strong_text {}
</style>
</head>
<body>
  <div class="big_strong_text">텍스트1</div>
  <div class="sub_title_text">텍스트2</div>
  <div class="strong">텍스트3</div>
</body>
</html>

속성이 추가될 때마다 css 클래스 속성도 추가해야 하고 이름도 생각해내야 하기 때문에 좋지 않다.

좋은 예

<html>
<head>
<style>
  h1.title {...}
  h2.title {}
  p.title {}
</style>
</head>
<body>
  <h1 class="title">텍스트1</div>
  <h2 class="title">텍스트2</div>
  <p class="title">텍스트3</div>
</body>
</html>

위계가 잘 잡혀있어서 이름 짓기가 좋다.

수긍하기 쉽게 이름 짓기

수긍하기 쉽게라는 것이 상황에 따라 달라지는 것이기에 정답은 없다 다만, 단순히 for 루프에서 index를 표현하고자 하는 변수에 index_of_for_loop라고 긁어 부스럼이 난 변수를 적을 필요는 없을 것이다.

기억하기 쉽게 이름 짓기

몇 가지 예시를 들어보자. 아마존의 S3의 원래 이름은 Simple Storage Service이다. 그렇지만 S3라고 하면 모두가 알아듣는다. MVC는 model view controller의 약자이지만 한번 들은 사람은 거의 다 알고 있다. 기억하기 쉽게 짓는 방법은 그냥 뇌의 용량을 적게 쓰도록 유도하는 것이다. 원래 알고 있는 것이거나, 비슷한 것이거나, 발음이 익숙하거나 하면 외우기 쉽다. 개인적으로는 남발하면 오히려 역효과가 날 수 있으니 적절한 포인트에 사용하는 게 좋을 것 같다.

입력하기 쉽게 이름 짓기

유독 타이핑 할 때 잘 틀리는 단어들이 있다. lambda, service, success, address, classes, parallel 등이다. 그래서 그런지 요즘에는 success 보다 ok도 종종 보인다. address 도 addr로 줄여 쓰기도 하고 class도 cls로 줄여 쓰기도 한다. 최근에는 IDE가 도와줘서 타이핑할 때 틀리는 일이 많지는 않지만, 이것도 한번 생각해봄직 하다.

결론

코드 리뷰가 거의 없던 시절에는 내 코드의 독자는 거의 나 혼자였다. 나 혼자만 리뷰어 같은 느낌이다. 그러나 최근에는 코드 리뷰가 많이 활발해졌다. 나의 코드를 읽는 사람이 최소한 한 명은 더 있는 셈이다. 그렇다면, 나도 코드를 작성할 때 최소한의 노력은 더 기울여야 하지 않을까 하는 마음에서 이 문서를 작성했다. 책들을 참고하면서 개인의 의견도 추가로 넣었는데, 이에 동의하지 않는 사람도 분명히 있을 것이다. 그렇기에 초반에 강조했던 다른 사람이 코드를 읽고 이해하는데 들어가는 시간을 최소화해야 한다는 원칙이 가장 중요하다. 같이 일하는 사람의 스타일에 맞추어서 계속해서 다듬어 가다 보면 조금 더 읽는 사람을 배려한 코드가 될 수 있을 거라 생각한다.