소스 파일 구성 규칙
Java 소스 파일은 명확한 구조를 따라야 하며, 다음 요소들이 순차적으로 배치되어야 합니다:
- 라이선스 또는 저작권 정보 (필요 시)
- package 선언문
- import 문들
- 단 하나의 최상위 클래스
각 섹션 사이에는 빈 줄 하나로 구분합니다. 예외적으로 package-info.java는 실제 클래스 없이 패키지 주석만 포함할 수 있습니다.
패키지 및 임포트 문 형식
package 문은 줄 바꿈 없이 한 줄로 작성됩니다. import 문은 와일드카드(*) 사용을 금지하며, 다음과 같은 순서로 그룹화하고 각 그룹 사이에 빈 줄을 삽입합니다:
- 정적 임포트
- com.google 패키지 (현재 파일이 해당 패키지 내부일 경우에만)
- 기타 서드파티 라이브러리 (android, com, junit 등 사전순)
- java 표준 라이브러리
- javax 관련 라이브러리
그룹 내 항목들은 알파벳 순으로 정렬되며, 중간에 빈 줄을 넣지 않습니다.
클래스 멤버 배치 원칙
클래스 내부 멤버들의 순서는 일관성과 논리성을 가져야 합니다. 일반적인 접근 방식은 필드 → 생성자 → 메서드 순서이며, 유사한 기능을 가진 메서드들은 함께 묶는 것이 좋습니다. 특히 오버로딩된 메서드나 생성자는 반드시 인접하게 배치되어야 하며, 시간 순서보다는 의미 기반 정렬을 우선시해야 합니다.
블록 형식 및 들여쓰기
모든 제어문(if, for, while 등)은 비어 있더라도 중괄호를 포함해야 하며, K&R 스타일을 따릅니다:
if (condition) {
doSomething();
} else {
doOther();
}
새로운 블록 진입 시마다 들여쓰기는 공백 2칸씩 증가하며, 탭 문자 사용은 금지됩니다. 빈 블록은 {} 형태로 간결하게 표현할 수 있으나, try-catch와 같이 복합 문맥에서는 여전히 줄 바꿈을 적용합니다.
줄 길이 및 자동 줄 바꿈
코드 라인은 80자 또는 100자로 제한되며, 이를 초과하는 경우 적절히 줄을 나눠야 합니다. 줄 바꿈 위치 선택 시 다음과 같은 우선순위를 따릅니다:
- 연산자 앞에서 줄 바꿈 (예:
+,.,&등의 이항 연산자) - 대입 연산자(
=) 뒤에서 줄 바꿈 - 메서드 이름과 괄호는 같은 줄 유지
- 쉼표는 앞쪽과 함께 유지
줄 바꿈 후 행들은 최소 4칸 이상 추가 들여쓰기를 수행하며, 여러 단계의 문법 구조가 중첩될 경우 더 깊은 들여쓰기가 허용됩니다.
공백 사용 기준
수평 공백은 코드 가독성을 높이는 데 활용되며, 다음 위치에 공백 하나를 삽입합니다:
- 제어문 키워드 뒤 (if, for, catch 등)
- 왼쪽 중괄호(
{) 앞 (특정 어노테이션 제외) - 이항/삼항 연산자 양쪽
- 콤마, 세미콜론, 오른쪽 괄호 뒤
- 변수 타입과 이름 사이 (예:
List<String> items) - 주석 시작 기호(
//) 앞뒤
수직 공백은 논리적 그룹 분리를 위해 사용되며, 연속된 멤버 사이, 메서드 내부 로직 블록 사이에 빈 줄을 삽입할 수 있습니다. 연속된 두 개 이상의 빈 줄은 권장되지 않습니다.
정렬 관행: 권장하지 않음
변수 선언이나 할당문에서 특정 기호를 맞추기 위한 가변 길이 공백 삽입(수평 정렬)은 스타일 일관성 유지 관점에서 권장하지 않습니다. 아래 예시는 허용되지만 유지 보수성이 낮습니다:
private int count;
private String name;
대신 자연스러운 들여쓰기만을 적용하는 것이 바람직합니다:
private int count;
private String name;
명명 규칙
식별자는 ASCII 문자와 숫자만 사용하며, 언더스코어 접두사/접미사를 피해야 합니다. 각 요소별 명명 방식은 다음과 같습니다:
- 클래스/인터페이스: UpperCamelCase (예:
HttpRequest,LinkedListNode) - 메서드/필드: lowerCamelCase (예:
calculateTotal(),userName) - 상수: 대문자 + 언더스코어 (예:
MAX_RETRY_COUNT,DEFAULT_TIMEOUT_MS) - 패키지: 전부 소문자, 단어 연결 (예:
com.example.service) - 제네릭 타입 변수: 단일 대문자 (예:
T,E) 또는 CamelCase + T 접미사 (예:RequestT)
특수 단어 처리 시 "IPv6", "iOS" 등은 전체를 소문자화한 후 첫 글자만 대문자로 조합합니다 (예: supportsIpv6OnIos()).
프로그래밍 관행
@Override 어노테이션은 가능한 모든 경우에 명시적으로 사용해야 하며, 정적 멤버 접근은 반드시 클래스 이름을 통해 이루어져야 합니다:
UserManager.getActiveUsers(); // ✅ 권장
instance.getActiveUsers(); // ❌ 비권장
catch 블록 내에서 예외를 무시할 경우 반드시 주석으로 그 의도를 명시해야 하며, 테스트 코드에서 예외 이름을 expected로 지정하면 주석 없이 생략 가능합니다:
try {
emptyList.get(0);
fail("Should throw exception");
} catch (IndexOutOfBoundsException expected) {
// Pass
}
Object.finalize() 재정의는 금지되며, 자원 해제는 try-with-resources 또는 명시적 close() 호출을 사용해야 합니다.
Javadoc 작성 기준
public 및 protected 멤버에는 기본적으로 Javadoc을 작성해야 하며, get/set 메서드처럼 자명한 경우는 예외입니다. Javadoc 블록 형식은 다음과 같습니다:
/**
* 계정 상태에 따라 사용자 접근 권한을 확인합니다.
*
* @param userId 검증할 사용자 ID
* @return 활성 상태면 true, 그렇지 않으면 false
* @throws UserNotFoundException 사용자 정보가 존재하지 않을 경우
*/
public boolean isAccessAllowed(String userId) { ... }
요약 문단은 완전한 문장 형태로 작성되며, "Returns..." 또는 "Gets..."로 시작하지 않고 마침표로 종료됩니다. @param, @return, @throws 순서로 태그를 배치하며 설명 내용은 비어 있으면 안 됩니다.