Naming Convention

🔥 서적을 바탕으로 한 내용 정리 느낌이 강한 문서입니다.
이런 방식을 사용하는구나 정도로만 알고, 이 내용이 원칙이 아님을 알립니다. 🙇

코드를 작성하면서 변수, 함수명을 짓는 부분은 항상 고민이 되는 부분이다.

뭔가 길게 쓰면 가독성이 떨어질 거 같고, 짧게 쓰면 당상 쓰기엔 편하지만 어떤 변수인지 정확하게 알기 힘들 수도 있고…

Clean Code 와 개발자의 글쓰기라는 서적을 읽으면서 Name Convention에 대한 내용을 정리해보려고 한다.

아래 블로그 글은 오픈소스에 작성된 함수, 변수, 클래스의 네이밍을 분석한 내용을 담고 있다. 한 번 살펴보면 재밌을 것(?) 같다.

오픈소스의 네이밍 특징들

위 블로그에서도 마찬가지지만 이름을 짓는 방식은 어느 특별한 방식이 있는 것이 아니라 우리가 알고 있는 단어를 연결하는 것만으로도 충분하다.

몇 가지의 규칙을 정하면 보다 쉽게 이름을 지을 수 있을 것이다.

표기법

변수, 함수, 클래스, 상수 마다 표기법을 달리하여 구분해준다.

클래스 → 파스칼 표기법

# 첫 글자를 대문자로 표시한다.
class animal # ---> ( X )

class Animal # ---> ( O )

함수, 변수 → 카멜 표기

# 카멜 표기법은 첫단어를 제외하고,
# 나머지 단어의 첫번째 글자만 대문자로 표기하는 방법

NumberCount = 0 
def CountingNumber(): return
# ---> ( X )

numberCount = 0
def countingNumber() : return
# ---> ( O )

상수 → 대문자 표기

# 상수의 경우 대문자로 표기한다.
# 단어와 단어사이 언더바(_)를 사용하여 구분한다.

ADULT_AGE = 19 

패키지, 모듈 → 소문자 표기

# 다른 이유들 보다 위의 함수, 변수, 클래스 등과
# 구별하기 위해서 소문자 표기를 하는 것을 규칙으로 한다.

from itertools from dropwhile

이름 잘 짓기

• ‘a’, ‘b’와 같이 의미없는 변수명은 사용하지 말자. 의도를 분명하게 하자.

  우리가 자주 사용하는 index를 뜻하는 i나 좌푯값을 의미하는 x , y는 사용해도 좋다. 하지만 의미 없는 변수명을 사용하는 것은 지양하자.

    d = 30
    m = 12
    y = 2022
    # ---> ( X )
  
    day = 30
    month = 12
    year = 2022
    # ---> ( O )
  
    # 더욱 의미가 통하도록 어떤 날짜 데이터인지
    # 알 수 있는 변수명이면 더 좋다.
    daySinceCreated = 15

• 검색이 쉬운 이름을 쓰자

  요즘 개발도구 (ex. VSCode)가 자동완성 기능을 제공하고 있기 때문에 변수명의 길이를 신경 써야 할 이유가 이전보다 많이 줄었다. 그래서 우리가 개발할 때 개발 환경에서 검색이 쉽도록 변수명을 정하는 것이 좋다.

  변수가 더 넓은 범주에서 사용될 경우 더 많이 사용되기 때문에 이 부분에 대해서 더 고려해야 한다.

• 복수형 ‘s’

  배열이나 복수의 의미를 부여하기 위해 변수명에 ‘s’를 사용한다. s라는 한 글자가 눈에 잘 들어오지 않기 때문에 Array, List라는 단어로 보다 명확하게 표시해주는 게 좋다.

    studentsName = [ ... ]
  
    studentNameArray = [ ... ]

• 약어 사용

  풀네임보다 약어가 더 익숙한 단어들은 약어를 사용하는 것이 더 의미가 잘 통한다.

    VeryImportantPersonArray = [ ... ]
    # -----> ( X )
  
    VIPNameArray = [ ... ]
    # -----> ( O )

• 함수 이름 짓는 방법

  함수가 동작하는 방법을 문장화하고, 그 문장을 최대한 간소화하여 이름을 짓는다.

    # 이름을 사용자 input을 통해 받아오는 경우
    def getUserName: return
  
    # 사용자의 이름을 받아오는 곳이 시스템상 여러 군데 일 경우
    # 변수명에 보다 자세히 명시할 수 있도록 한다.
    def getUserNameFromInput: return

좋은 이름의 기준 SMART

• Easy To Search

  위에서 설명한 검색하기 쉬운 변수명과 동일한 내용으로, 프로젝트가 커지면서 비슷한 이름들이 나오게 될 수도 있다. 이때는 변수명 앞에 상위 범주의 이름을 추가해서 비슷한 변수명 사이에서도 어느 정도 의미가 구분되도록 해준다면 더 검색하기 쉽다.

    userRegister
    userCart
    userBuyer
    userManager

• Easy To Mix

  CSS에서는 유사한 class 이름을 아주 많이 만들게 된다. postTitle, headTitle과 같이 모든 이름을 만들기보다, Sementic tag와 같이 본연의 의미를 가지고 있는 요소와 함께 사용하여 h1.title, table.title 변수명이 불필요하게 늘어나는 것을 방지할 수 있다.

• Easy To Agree

  코드를 보는 모든 사람이 수긍할 수 있는 변수명이어야 한다.

  우리가 자주 사용하는 i의 경우 좁은 범위, 단일 반복문 내에서 사용한다면 굳이 기본적인 의미를 새로운 변수명으로 풀어낼 이유가 없다. 하지만 i가 더 넓은 범위에서 사용된다면 다른 코드에서 의미가 혼동될 수도 있기 때문에 변수를 보았을 때 누구나 이해할 수 있는 변수명을 사용하는 것이 좋다.

• Easy To Remember

  기억하기 쉬운 보편적인 변수명을 사용하는 것이 좋다.

  굳이 특별하고, 센스있는 변수명들 보다 보편적인 단어로 구성된 변수명이 기억에 더 오래 남을 수 있다.

• Easy To Type

  자동완성 기능으로 다른 부분보다 덜 고려해도 되는 부분이라고 생각한다. 연속된 철자, 묵음과 같은 철자가 헷갈리거나, 타이핑하기 힘든 변수명은 고려해보는 것이 좋다.

    # 연속된 철자
    success, button, classes
    # 묵음
    lambda, debt
    # ie/ei
    retrieve, receive, friend
    # tion/sion
    position, commission
    # uous/us/ous
    continuous, fabulous

이름과 주석

주석은 양날의 검이라고 생각한다.

코드에 대한 보충 설명을 해줄 수도 있지만, 부적절한 주석으로 인해 코드 가독성을 오히려 해칠 수도 있다.

주석은 코드를 읽는 ‘다른 사람'을 위한 것이다.

예를 들어 함수가 하는 역할에 관해서 설명한다고 할 때, 변수명에 최대한 함수가 담당한 역할을 담을 수 있도록 하고, 변수명에 차마 담지 못했던 부분을 주석으로 담는 것을 추천한다.

imHungrySoLetsEatSomething()
youAreHungrySoLetsEatSomething()
imBoredSoLetsEatSomething()

#---------------------------
letsEatSomething() # 내가 배고플때
letsEatSomething() # 네가 배고플때
letsEatSomething() # 내가 심심할때

# 비슷한 상황에서 유사한 동작을 하는 함수의 경우
# 리팩토링하여 하나의 함수로 합치고,
# 각 상황을 주석으로 설명했다.

Opinion

나는 팀 개발 경험보다 1인 개발 경험이 더 많아서 내가 보기 편하고 이해할 수 있는 방식으로 그때 그때 변수명을 만들어왔다. 하지만 내 코드를 다시봤을 때 무슨 의미를 담고 있는 변수인지 이해하기 힘든 이름들이 많이 보였다. 다른 사람이 내 코드를 봤을 때 더 이해하기 힘들 것이다.

위에서 설명한대로 자동 완성 기능이 아주 잘되어있기 때문에 이런 부분을 간과하고 넘어갈 수 도 있다

이후 내가 속할 팀의 Convention이 존재할 것이다. 마냥 따라가기보다 나만의 기준을 가지고, 의견을 제시하면 팀 문화에 좋은 영향력을 줄 수 있지 않을까 하는 생각을 했다.

그래서 이번 기회에 두 개의 서적을 보면서 Naming Convention에 대해 정리해보고 싶었다.