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

1. 네이밍 컨벤션의 중요성

소프트웨어 개발 과정에서 코드를 읽는 시간은 코드를 작성하는 시간보다 압도적으로 길다. 따라서 변수나 함수의 이름은 코드의 의도를 파악할 수 있게 해주는 중요한 단서가 된다.

일관된 네이밍 컨벤션을 사용하면 팀 내 의사소통 비용을 줄일 수 있으며 시스템 전반의 협업 효율성과 유지보수성을 높이는 데 도움이 된다.

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

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

네이밍 컨벤션에는 여러 가지 표기 방식이 존재한다. 각 스타일은 사용 목적과 환경에 따라 적절하게 선택되며 대표적인 이름 표기법은 다음과 같다.

- PascalCase (UpperCamelCase)

모든 단어의 첫 글자를 대문자로 표기하는 방식

객체 지향 프로그래밍에서의 클래스, 인터페이스, 구조체 명명에 사용된다. Java, C#, TypeScript 등 대부분의 언어에서 타입을 정의할 때 표준으로 사용된다.

예시) UserAccount, PaymentService, OrderRepository

- camelCase (lowerCamelCase)

첫 번째 단어는 소문자로 시작하고 두 번째 단어부터 첫 글자를 대문자로 표기하는 방식

변수, 함수/메서드 명명에 사용된다. Java, JavaScript의 핵심 표준 방식이다.

예시) userId, calculateTotal(), isAvailable

- UPPER_SNAKE_CASE (SCREAMING_SNAKE_CASE)

모든 문자를 대문자로 표기하며 단어 사이를 언더바(_)로 연결하는 방식

상수(Constant) 정의에 사용된다. 프로그램 실행 중 값이 변하지 않는 고정된 데이터를 나타낸다. 대문자를 사용하여 코드 내에서 일반 변수와 상수를 시각적으로 분리하기 위해 사용한다.

예시) MAX_LIMIT, API_KEY, DEFAULT_TIMEOUT

- lower_snake_case

모든 문자를 소문자로 표기하며 단어 사이를 언더바(_)로 연결하는 방식

Python, Ruby, C 언어의 변수 및 함수명, 데이터베이스의 컬럼명, JSON 키값에 주로 사용된다. 공백을 허용하지 않는 시스템 환경에서 가독성을 확보하기 위한 표준이다.

예시) user_id, created_at, get_data()

- kebab-case

모든 문자를 소문자로 표기하며 단어 사이를 하이픈(-)으로 연결하는 방식

HTML 태그의 ID/Class, CSS 속성명, URL 경로에 사용된다. 대소문자를 구분하지 않는 환경에서 단어를 구분하기 위한 최적의 방식이다. 프로그래밍 언어의 변수명으로는 하이픈이 마이너스(-) 연산자로 인식되어 사용이 불가능한 경우가 많다.

예시) main-container, background-color, /api/user-profile

3. 실제 코드에서의 네이밍 원칙

단순한 표기법 외에도 실제 코드 작성 시에는 몇 가지 중요한 네이밍 원칙을 고려해야 한다. 좋은 이름은 코드의 의도를 명확하게 전달하며 가독성과 유지보수성을 높인다.

• 의미 있는 이름 사용
  변수명은 용도를 명확히 알 수 있어야 한다. 단일 문자나 의미 없는 약어 사용을 지양한다.
• Boolean 변수의 접두사
  참/거짓을 나타내는 변수는 질문 형태의 접두사를 붙여 가독성을 높인다.
  예시) isAvailable, hasToken, canExecute, shouldRedirect
• 약어 처리 방식
  HTTP, URL, API와 같은 약어를 처리할 때 팀의 규칙에 따라 일관성을 유지한다.
  예시) getHTTPRequest 혹은 getHttpRequest
• 동사-명사 구조
  함수나 메서드는 동작을 수행하므로 동사로 시작하는 것이 관례이다.
  예시) getUserData(), inputValidator(), sendEmail()

4. 네이밍 컨벤션 적용 예시

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

// 나쁜 예
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에서는 리소스 중심의 URL 설계를 사용하는 것이 일반적이다. URL에 /api/v1과 같은 버전 정보를 명시하면 향후 API 변경에 유연하게 대응할 수 있다.

또한 리소스 경로는 명사 형태의 복수형을 사용하는 것이 일반적이며 kebab-case를 사용하는 경우도 많다. 쿼리 파라미터는 일반적으로 camelCase를 사용한다.

또한 URL에서 동사를 사용하는 대신 HTTP 메서드(GET, POST, PATCH 등) 자체로 동작을 표현하는 것이 권장된다.

-- 좋은 예
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 환경에서도 호환성이 높다는 장점이 있다.