Java 비즈니스 아키텍처의 파일명 및 변수명 명명 규칙: 효율적이고 유지보수 가능한 코드를 위한 가이드

소프트웨어 개발의 핵심은 읽기 쉽고 유지보수 가능한 코드를 작성하는 것입니다. 특히, Java 기반 비즈니스 애플리케이션을 개발할 때는 명확하고 일관된 명명 규칙을 따르는 것이 중요합니다. 이러한 규칙은 협업 효율성을 높이고, 코드 리뷰와 디버깅 과정을 단축시키며, 새로운 팀원이 프로젝트를 빠르게 이해할 수 있도록 돕습니다. 이 글에서는 Java 비즈니스 아키텍처를 구성하는 파일명과 변수명 명명 규칙을 상세히 다룹니다.

---

1. 파일명 명명 규칙

Java 비즈니스 아키텍처는 여러 계층(Layer)으로 구성되며, 각 계층은 특정한 역할을 담당합니다. 각 계층의 파일명은 해당 역할을 반영해야 합니다.

1.1. 컨트롤러 클래스 (Controller)

• 역할: 사용자 요청을 처리하고, 서비스 계층과 상호작용합니다.
• 파일명 규칙: [EntityName]Controller
  • 예:
    • UserController.java
    • OrderController.java
• 명명 원칙:
  • 이름은 반드시 PascalCase로 작성합니다.
  • Controller 접미사를 추가하여 역할을 명확히 합니다.

1.2. 서비스 클래스 (Service)

• 역할: 비즈니스 로직을 처리하며, 데이터 액세스 계층과 상호작용합니다.
• 파일명 규칙: [EntityName]Service
  • 예:
    • UserService.java
    • OrderService.java
• 명명 원칙:
  • Service 접미사로 클래스의 역할을 명확히 표현합니다.
  • 동일 엔터티의 비즈니스 로직은 하나의 서비스 클래스로 관리합니다.

1.3. 리포지토리 클래스 (Repository)

• 역할: 데이터베이스와의 상호작용을 처리합니다.
• 파일명 규칙: [EntityName]Repository
  • 예:
    • UserRepository.java
    • ProductRepository.java
• 명명 원칙:
  • JPA를 사용하는 경우, 인터페이스로 정의하며 Spring Data JPA 규칙을 따릅니다.

1.4. DTO 클래스 (Data Transfer Object)

• 역할: 데이터를 전송하거나 반환하기 위한 객체를 정의합니다.
• 파일명 규칙: [EntityName]DTO
  • 예:
    • UserDTO.java
    • OrderDTO.java
• 명명 원칙:
  • DTO 접미사를 추가합니다.
  • 데이터 구조를 간단히 표현하고, 필요하지 않은 데이터는 포함하지 않습니다.

1.5. 엔터티 클래스 (Entity)

• 역할: 데이터베이스 테이블과 매핑되는 객체를 정의합니다.
• 파일명 규칙: [EntityName]
  • 예:
    • User.java
    • Order.java
• 명명 원칙:
  • 이름은 반드시 단수형으로 작성합니다.
  • PascalCase를 사용합니다.

---

2. 변수명 명명 규칙

변수명은 코드 가독성과 유지보수성에 큰 영향을 미칩니다. 변수명을 정의할 때는 다음과 같은 원칙을 따릅니다.

2.1. 일반 변수

• 규칙:
  • 변수명은 CamelCase를 사용합니다.
  • 가능한 한 구체적이고 의미 있는 이름을 사용합니다.
• 예시:

  String userName; // 올바름
  int orderCount; // 올바름
  String a; // 잘못된 예 (의미 없음)

2.2. 상수

• 규칙:
  • 상수명은 대문자와 언더스코어를 사용합니다.
  • 가능한 한 구체적이고 의미 있는 이름을 사용합니다.
• 예시:

  public static final int MAX_RETRY_COUNT = 3;
  public static final String DEFAULT_USER_ROLE = "USER";

2.3. 컬렉션 변수

• 규칙:
  • 변수명이 복수형을 포함하여 데이터 구조를 명확히 표현합니다.
• 예시:

  List<String> userNames;
  Map<String, Integer> productStock;

2.4. Boolean 변수

• 규칙:
  • is, has, can, should 등의 접두사를 사용하여 논리 상태를 명확히 표현합니다.
• 예시:

  boolean isActive;
  boolean hasPermission;
  boolean canEdit;

---

3. 메서드명 명명 규칙

메서드는 동작을 나타내므로, 명사는 피하고 동사를 사용해야 합니다.

3.1. Getter와 Setter

• 규칙:
  • 변수명에 따라 get과 set 접두사를 사용합니다.
• 예시:

  public String getUserName();
  public void setUserName(String userName);

3.2. 동작 메서드

• 규칙:
  • 동작을 나타내는 동사로 시작하며, CamelCase를 사용합니다.
  • 메서드의 목적을 명확히 표현합니다.
• 예시:

  public void saveUser(User user);
  public List<Order> findOrdersByDate(LocalDate date);

---

4. 패키지명 명명 규칙

4.1. 규칙

• 패키지명은 소문자를 사용합니다.
• 도메인 이름의 역순으로 구성하며, 기능별로 세분화합니다.

4.2. 예시

• 기본 도메인: com.example
• 패키지 구조:

  com.example.controller
  com.example.service
  com.example.repository
  com.example.dto
  com.example.entity

---

5. 프로젝트 구조 예시

다음은 실제 Java 프로젝트에서 추천하는 디렉토리 및 명명 구조 예시입니다.

src/main/java/com/example
├── controller
│   ├── UserController.java
│   ├── OrderController.java
├── service
│   ├── UserService.java
│   ├── OrderService.java
├── repository
│   ├── UserRepository.java
│   ├── ProductRepository.java
├── dto
│   ├── UserDTO.java
│   ├── OrderDTO.java
├── entity
│   ├── User.java
│   ├── Order.java

---

6. 테스트 코드 명명 규칙

6.1. 테스트 클래스

• 규칙:
  • 테스트 대상 클래스명에 Test를 접미사로 추가합니다.
• 예시:

  public class UserServiceTest {}

6.2. 테스트 메서드

• 규칙:
  • 테스트하는 기능을 설명하는 방식으로 이름을 작성합니다.
  • should, when, given 등을 포함하여 테스트 의도를 명확히 합니다.
• 예시:

  @Test
  public void shouldReturnUserWhenUserIdIsValid() {}

---

7. 결론

Java 비즈니스 아키텍처에서 명명 규칙을 준수하면 코드 가독성과 유지보수성이 크게 향상됩니다. 위에서 설명한 파일명, 변수명, 메서드명, 패키지명 규칙은 개발팀 전체가 동일한 기준을 따르도록 도와줍니다. 이러한 명명 규칙을 참고하여 더 나은 코드 품질을 유지하세요!