Java, Spring, Spring boot Coding Conventions

Java, Spring, 그리고 Spring Boot 개발 시 권장되는 코딩 컨벤션(Coding Conventions)을 정리한 것입니다. 각 조직이나 팀마다 세부 사항이 다를 수 있지만, 다음 가이드라인을 참고하면 표준적이고 일관성 있는 코드를 작성할 수 있습니다.

---

1. Java 코딩 컨벤션

1.1 패키지/클래스/메서드/변수 명명 규칙

1. 패키지명

   • 소문자 사용, 일반적으로 도메인 역순으로 구성.
   • 예: com.example.myapp

2. 클래스/인터페이스명

   • 파스칼 케이스(PascalCase) 사용.
   • 명사 형태, 인터페이스는 ‘able’ 또는 ‘ible’로 끝나는 경우 많음(선택 사항).
   • 예: public class UserService, public interface Runnable

3. 메서드명

   • 카멜 케이스(camelCase) 사용.
   • 동사 또는 동사구 형태, 역할을 명확히.
   • 예: getUserById(), calculateTotalPrice()

4. 변수명

   • 카멜 케이스(camelCase) 사용.
   • 의미가 명확하도록 작성, 축약형 지양.
   • 예: int userCount, String firstName

5. 상수명

   • 모든 문자를 대문자로, 단어 간 구분은 언더스코어(_) 사용.
   • 예: public static final int MAX_SIZE = 100;

1.2 들여쓰기/공백/중괄호

1. 들여쓰기
   • 공백 2칸 또는 4칸(팀 규칙에 따라 결정), 탭 대신 공백 사용 권장.
2. 중괄호 위치
   • K&R 스타일(한 줄 위에 여는 중괄호):

     public void example() {
         // ...
     }

3. 띄어쓰기
   • 연산자 주위에 공백 권장: int sum = a + b;
   • if, for 등의 키워드 뒤에 공백: if (condition) { ... }

1.3 주석(Comment)

1. Javadoc 주석
   • 클래스, 메서드, 필드에 대한 설명 사용:

     /**
      * 사용자 정보를 반환합니다.
      * 
      * @param id 사용자 ID
      * @return 사용자 객체
      */
     public User getUserById(Long id) { ... }

2. 라인 주석
   • 불분명한 로직 또는 주의가 필요한 부분:

     // 사용자 정보를 DB에서 조회
     User user = userRepository.findById(id);

1.4 기타 권장 사항

• 에러 처리: 충분히 의미 있는 예외를 던지고, try-catch 시 구체적인 메시지 로그.
• 컬렉션 타입: 제네릭(Generics)을 사용해 타입 안정성 보장.
• 코드 길이 제어: 메서드가 너무 길어지지 않도록 분리해서 작성.

---

2. Spring 코드 컨벤션

2.1 패키지 구조

일반적으로 다음과 같은 계층형 아키텍처를 사용:

com.example.myapp
 ├─ controller (또는 web)
 ├─ service
 ├─ repository
 ├─ domain (또는 model, entity)
 └─ config

• Controller/Web: HTTP 요청/응답 처리.
• Service: 비즈니스 로직 처리.
• Repository/DAO: 데이터베이스 접근.
• Domain/Model/Entity: 엔티티 클래스, VO, DTO 등.
• Config: 설정 관련 클래스.

2.2 클래스 및 어노테이션 규칙

1. Controller 클래스

   • @RestController 또는 @Controller 사용.
   • 요청 경로를 @RequestMapping(클래스 레벨) 또는 @GetMapping, @PostMapping(메서드 레벨)로 선언.

2. Service 클래스

   • @Service 사용.
   • 트랜잭션이 필요한 경우 @Transactional 부여.

3. Repository 클래스

   • @Repository 사용 또는 JPA에서는 CrudRepository, JpaRepository 등을 상속.
   • 데이터 접근 로직 구현.

4. Entity 클래스

   • @Entity, @Table 사용.
   • 필드는 @Id, @Column으로 매핑.

2.3 Bean 주입 방식

• 생성자 주입 권장:

  @Service
  public class UserService {
      private final UserRepository userRepository;
  
      public UserService(UserRepository userRepository) {
          this.userRepository = userRepository;
      }
      // ...
  }

• 필드 주입은 테스트나 유지보수 관점에서 비추천.

• Setter 주입은 선택적인 의존성에만 사용.

2.4 예외 처리

• ControllerAdvice와 @ExceptionHandler를 사용하여 전역 예외 처리.
• 예외 발생 시 명확한 메시지와 상태 코드를 반환.

---

3. Spring Boot 코드 컨벤션

Spring Boot는 Spring을 보다 간편하게 사용할 수 있도록 도와주는 프레임워크이며, 다음 사항을 지키면 좋습니다.

3.1 애플리케이션 구조

com.example.demo

├─ DemoApplication.java  (main class)
├─ controller/
├─ service/
├─ repository/
├─ domain/
└─ config/

• 메인 클래스(예: DemoApplication)는 루트 패키지에 위치해 컴포넌트 스캔이 패키지 하위까지 적용되도록 함.

3.2 프로퍼티/설정 파일 관리

• application.properties 또는 application.yml 파일에 환경별 설정(profiles) 구분 (application-dev.properties, application-prod.properties 등).
• 빈 설정은 최대한 @ConfigurationProperties를 사용해 명시적으로 관리.

3.3 자동 설정(Autoconfiguration)과 사용자 설정

• Spring Boot가 제공하는 Auto Configuration을 최대한 활용.
• 필요 시 @Configuration 클래스로 추가 설정.

3.4 로깅(Logging)

• Spring Boot는 기본적으로 Logback 사용.
• application.properties에서 로깅 레벨 설정:

  logging.level.org.springframework=INFO
  logging.level.com.example=DEBUG

---

결론

• Java 코드 컨벤션은 Oracle 스타일 가이드를 기본으로 작성하며, 클래스/메서드/변수명에 대한 규칙, 들여쓰기, 주석 스타일 등을 지킵니다.
• Spring 코드 컨벤션은 계층형 아키텍처를 따르며, 각 계층에 적절한 어노테이션(@Controller, @Service, @Repository)을 사용합니다.
• Spring Boot는 Spring을 보다 편리하게 사용하기 위한 것으로, 루트 패키지 구조, 자동 설정, 프로파일 관리 등을 활용해 더욱 간결한 코드를 작성합니다.

이러한 컨벤션을 따르면 프로젝트의 가독성, 유지보수성, 그리고 협업 효율성이 높아지며, 일관된 코드를 작성할 수 있습니다.

추가 학습 자료

• 캠퍼스 핵데이 Java 코딩 컨벤션
• naver/hackday-conventions-java
• naver/hackday-conventions-java