🤝 읽기 좋은 코드를 위한 네이밍 컨벤션 가이드

네이밍 컨벤션이 중요한 이유? 

개발 과정에서 가장 많이 하는 일은 사실상 코드 작성보다 코드를 읽는 일이다. 이때 변수나 함수의 이름은 코드의 의미를 빠르게 파악할 수 있게 해주는 가장 중요한 단서이다. 또한 일관된 네이밍 컨벤션은 팀 전체의 협업 효율성과 유지보수성을 높여준다. 

범용적으로 사용되는 네이밍 스타일에 대해 알아보자. 
 

이름 표기 방식 (Case 스타일)

네이밍 컨벤션에는 여러 가지 표기법이 존재한다. 각 스타일은 쓰임새에 따라 적절히 선택되며 아래는 대표적인 이름 표기법들과 설명이다. 

PascalCase 
- 각 단어의 첫 글자를 대문자로 연결 

camelCase 
- 첫 단어는 소문자 이후 단어는 대문자로 시작 

UPPER_SNAKE_CASE 
- 모든 문자를 대문자로 쓰고 단어는 밑줄(_)로 구분 

lower_snake_case 
- 모든 문자를 소문자로 쓰고 단어는 밑줄(_)로 구분 

kebab-case 
- 모든 문자를 소문자로 쓰고 단어는 하이픈(-)으로 구분 

BEM 
- block__element--modifier 패턴 (CSS 클래스 네이밍) 


각각의 케이스는 주로 다음과 같이 사용된다. 
 

• 클래스/타입/인터페이스/컴포넌트: PascalCase
• 함수/메서드/변수/쿼리 파라미터: camelCase
• 상수/환경변수/플래그/에러 코드 키: UPPER_SNAKE_CASE
• RDB 테이블/컬럼: lower_snake_case
• 디렉터리/파일/URL: kebab-case
• CSS 클래스: BEM 

위에서 소개한 네이밍 스타일을 실제 코드에 적용해 보자. 
 

// 나쁜 예
class user_service {}
const defaultTimeout = 5000
function Find_active_members(p, ps)

// 좋은 예
class UserService {}
const DEFAULT_TIMEOUT_MS = 5000
function findActiveMembers(page, pageSize)

물론 네이밍에 정답은 없지만 일반적으로는 다음과 같은 원칙을 따른다. 상수는 모두 대문자(UPPER_SNAKE_CASE)로 작성하고 변수명과 함수명은 축약을 피하고 가능한 명확한 이름을 사용하는 것이 유지보수와 협업에 유리하다. 
 

// 나쁜 예
src/
  EmployeeList/
    employee_list.tsx
  componentsShared/
    my-button.tsx
    
// 좋은 예
src/
  employee-list/
    EmployeeList.tsx
    EmployeeRow.tsx
  shared-components/
    Button.tsx

폴더 및 파일 네이밍에도 일관된 컨벤션을 적용하는 것이 좋다. 디렉터리/파일은 kebab-case를 주로 사용한다. 
 

// 나쁜 예
GET  /api/v1/getMemberList
POST /api/v1/deactivateMember?id=42

// 좋은 예
GET  /api/v1/members?page=1&pageSize=20
PATCH /api/v1/members/42 { "isActive": false }

HTTP API 네이밍의 경우 /api/v1처럼 URL에 버전을 명시하면 추후 변경에 유연하게 대응 가능하며 리소스 경로는 명사 형태의 복수형(+kebab-case)를 사용한다. 단 쿼리 파라미터의 경우 camelCase를 일반적으로 사용한다.  

또한 가급적 동사는 지양하고 HTTP 메서드 자체로 동작을 표현하는 것이 좋다. 
 

-- 좋은 예
CREATE TABLE member (
  id         BIGINT       PRIMARY KEY,
  email      VARCHAR(255) NOT NULL UNIQUE,
  is_active  BOOLEAN      NOT NULL DEFAULT TRUE,
  created_at TIMESTAMP    NOT NULL
);
CREATE UNIQUE INDEX uq_member__email ON member(email);
CREATE INDEX ix_member__created_at ON member(created_at);

관계형 데이터베이스에서는 테이블, 컬럼명에 lower_snake_case를 사용하는 것이 일반적이다. SQL 키워드와 시각적으로 구분이 쉽고 대소문자 구분이 없는 RDBMS 에서의 호환성이 높기 때문이다. 
 

위와 같은 스타일을 참고하여 프로젝트에 맞는 네이밍 컨벤션을 정하는 것이 중요하다. 컨벤션을 정할 때는 다음과 같은 점을 유의하면 좋다. 

1) 전체 코드베이스에서 일관된 규칙을 적용한다. 
2) 개인 기준이 아닌 팀 전체의 합의를 통해 컨벤션을 정의한다. (+문서화)
3) usr, cnt, temp 등 의미가 모호한 축약은 피하고 직관적인 이름을 사용한다. 
4) 의미 있는 네이밍을 사용한다. 
5) 사용 중인 언어나 프레임워크의 컨벤션을 고려한다. 

일관된 컨벤션은 코드를 읽는 사람에 대한 배려이자 협업의 기본이다. 팀과 프로젝트에 맞는 네이밍 규칙을 정하고 잘 지켜나가자!