[JAVA] Java Code Conventions ( 자바 코드 컨벤션 )

이 글을 자바 코딩 컨벤션을 익히기 위한 글로 공식문서를 번역한 것을 정리한 것입니다. 최소한의 예시만 있기 때문에 자세히 알고 싶다면 공식 문서를 참고하기 바랍니다.

1. 개요

코딩 규칙은 여러가지 이유에서 프로그래밍에 있어서 중요하다.

1. 소프트웨어를 개발하는 일련의 모든 과정에 들어가는 비용 중 80%가 유지보수에 쓰여진다.
2. 소프트웨어의 유지보수를 그 소프트웨어를 직접 개발한 개발자가 담당하는 경우는 거의 보기 힘들다.
3. 코딩 규칙을 지키면 다른 개발자가 그 소스 코드를 처음 보았을 때, 더 빠른 시간 안에 이해할 수 있도록 도와주기 때문에, 소프트웨어의 가독성이 높아진다.
4. 개발자가 자신의 소스 코드를 제품으로 팔려고 한다면, 자신이 작성한 다른 소스 코드들과 잘 어울리도록 패키지(Package)를 적절하게 구성할 필요가 있다.

2. 파일 이름

1. README : 특정 디렉토리의 내용을 요약하는 파일 이름으로 사용
2. GNUmakefile : make파일 이름으로 사용, 소프트웨어를 빌드할 때는 gnumake 명령어를 사용

3. 파일 구조

• 파일은 빈 줄이나 다른 구역임을 나타내주는 주석으로 나누어지는 여러 구역 (section)들로 구성되어 있다.
• 2000 라인을 넘는 파일은 이해하기가 쉽지 않기 때문에 될 수 있으면 피해야 한다.

1. 자바 소스 파일
   • 각각의 자바 소스 파일은 하나의 public 클래스 또는 인터페이스를 가진다. Private 클래스들과 인터페이스들이 public 클래스와 연결 되어 있을 때, public 클래스와 같은 파일에 private 클래스들과 인터페이스를 넣을 수 있다. Public 클래스는 파일에서 첫번째 클래스 또는 인터페이스이여야 한다.
   • 자바 소스 파일은 다음과 같은 순서를 가진다.
   1. 시작 주석
   2. Package 문과 Import 문
   3. Class 와 Interface 선언

       /*
       * Class name
       * Version information
       * Date
       * CopyRight
       */

2. Package 문과 Import 문
   • 대부분의 자바 소스 파일에서 주석이 아닌 첫번째 줄은 package 문이다. 그 후에, import 문이 뒤따라 나온다.

       package java.test
       import java.test.test

   • 주의 : Package는 한번만 선언되어야 하고, package 이름의 첫번째 부분은 모두 소문자 ASCII 문자를 사용해야 하고, 첫번째 레벨의 도메인 이름들(com, edu, gov, mil, net, org)중에 하나이거나 1981년 ISO Standard 3166에서 정의된 영어 두 문자로 표현되는 나라 구별 코드 중에하나이여햐 한다.
3. Class와 Interface 선언
   • 아래는 Class 또는 interface 선언의 일부분들을 나타나는 순서에 따라 보여준다.
   1. 클래스, 인터페이스 문서화 주석
   2. 클래스, 인터페이스
   3. 필요한 경우 클래스, 인터페이스 구현 주석
   4. 클래스 변수
   5. 일반 변수
   6. 생성자
   7. 매서드

4. 들여쓰기

• 4개의 빈칸 들여쓰기 단위로 사용한다. 들여쓰기의 정확한 구현은 정해져 있지 않다. 탭은 4개의 빈칸이 아니라, 8개의 빈칸으로 설정하는 것이 좋다.

1. 한 줄의 길이
   • 한 줄에 80자 이상 쓰는 것은 대부분의 터미널(terminal)과 툴에서 다룰 수 없기 때문에 피해야 한다.
2. 줄 나누기
   • 하나의 식이 한줄에 들어가지 않을 때에는, 다음과 같은 일반적인 원칙들을 따라서 두 줄로 나눈다.
   1. 콤마 후에 두 줄로 나눈다.
   2. 연산자 앞에서 두줄로 나눈다.
   3. 레벨이 낮은 원칙 보다는 레벨이 높은 원칙에 따라 두 줄로 나눈다.
   4. 앞줄과 같은 레벵의 식이 시작되는 새로운 줄은 앞줄과 들여쓰기를 일치시킨다.
   5. 만약 위의 원칙들이 코드를 더 복잡하게 하거나 오른쪽 끝을 넘어간다면, 대신에 8개의 빈칸을 사용해 들여쓴다.

5. 주석

• 자바 프로그램은 두 가지 종류의 주석을 지원한다. /* ... */ 와 // 이다. 이때 주석은 코드 자체만 가지고는 알 수 없는 추가적인 정보만을 포함하고 있는 것이 좋다. 즉 중요하거나 코드만으로는 명확하지 않은 프로그램 설계에 대한 추가 설명을 포함하는 것이 적절하다.
• 주석을 별표 또는 다른 문자를 사용하여 그린 큰 사각현에 넣은 방법은 피하도록 하자.
• 주석은 폼 피드나 백스페이스와 같은 특수 문자를 포함해서는 안된다.

1. 블록 주석
   • 블록 주석은 파일, 메서드, 자료구조, 알고리즘에 대한 설명을 제공할 때 사용된다. 블록 주석은 각각의 파일이 시작될 때와 메서드 전에 사용된다. 또한 메서드 안에서와 같이 다른 장소레서도 사용될 수 있다. 메서드 안에 존재하는 블록 주석은 주석이 설명하는 코드와 같은 단위에 들여쓰기를 해야 한다.
2. 한 줄 주석
   • 짧은 주석은 뒤따라 오는 코드와 같은 동일한 들여쓰기를 하는 한 줄로 작성할 수 있다. 만약 주석이 한 줄에 다 들어가지 않는다면, 블록 주석 형식을 따라야한다. 한줄 주석은 빈 줄로 시작되어야한다.
3. 꼬리 주석
   • 아주 짧은 주석이 필요한 경우 주석이 설명하는 코드와 같은 줄에 작성한다. 하지만 실제 코드와는 구분 될 수 있도록 충분히 멀리 떨어뜨려야 한다.
4. 줄 끝 주석
   • 주석 기호 //는 한 줄 모두를 주석 처리하거나 한 줄의 일부분을 주석 처리해야 할 때 사용할 수 있다. 긴 내용을 주석에 포함하기 위해서 연속되는 여러 중에 이 주석을 사용하는 것은 안되지만, 어떤 코드의 일부분을 주석 처리하기 위해서 여러 줄에 연속해서 사용하는 것은 허락된다.
5. 문서화 주석
   • 문서화 주석은 자바 클래스, 인터페이스, 생성자, 메서드 그리고 필드들을 설명한다. 각각의 문서화 주석은 주석 경계 기호인 /** ... */ 안으로 들어간다. 그리고, 각각의 문서화 주석은 클래스, 인터페이스 그리고 멤버 당 하나씩 가진다. 문서화 주석은 선언 바로 전에 나와야 한다.

6. 선언

1. 한 줄당 선언문의 수
   • 한 줄에 하나의 선언문을 쓰는 것이 주석문 쓰는 것을 쉽게 해주기 때문에 한 줄에 하나의 선언문을 쓰는 것이 좋다.
2. 초기화
   • 지역 변수의 경우, 지역 변수를 선언할 때 초기화 하는 것이 좋다. 변수의 초기화 값이 다흔 계산에 의해서 결정되는 경우라면, 변수를 선언할 때 초기화 하지 않아도 좋다.
3. 배치
   • 선언은 블록의 시작에 위치해야 한다. ( 보통 블록은 중괄호 ) 변수를 처음 사용할 때까지 변수의 선언을 미루지 말아라, 이러한 경우 부주의한 프로그래머들을 혼돈에 빠뜨릴 수 있고, 영역내에서 코드를 이동해야 하는 경우에 문제를 야기시킬 수 있다.
4. 클래스와 인터페이스의 선언
   • 자바 클래스와 인터페이스를 선언할 때, 다음과 같은 원칙을 따르도록 하자.
   1. 메서드 이름과 그 메서드의 파라미터 리스트의 시작인 괄호 사이에는 빈 공간이 없어야 한다.
   2. 여는 중괄호는 클래스/인터페이스/메서드 선언과 동일한 줄의 끝에 사용하자.
   3. 닫는 중괄호는 null 문인 경우를 제외하고는, 여는 문장과 동일한 들여쓰기를 하는 새로운 줄에서 사용하자.

7. 문(Statements)

간단한 문

• 각각의 줄에는 최대한 하나의 문만 사용하도록 한다.

복합문

• 복합문은 중괄호로 둘러싸여진 문들의 리스트를 포함하는 문이다.

1. 둘러 싸여진 문들은 복합문보다 한 단계 더 들여쓰기를 한다.
2. 여는 중괄호는 복합문을 시작하는 줄의 마지막에 위치해야 한다. 닫는 중괄호는 새로운 줄에 써야 하고, 복합문의 시작과 같은 들여쓰기를 한다.
3. 중괄호들이 if-else 문이나 for 문 같은 제어 구조의 일부분으로 사용되어질 때에는 이러한 중괄호들이 모든 문들을 둘러싸는데 사용되어져야 한다. 이렇게 사용하는 것이 중괄호를 닫는 것을 잊어버리는 것 때문에 발생하는 버그를 만들지 않고, 문을 추가하는 것에 큰 도움을 준다.

return 문

• 값을 반환하는 return 문은 특별한 방법으로 더 확실한 return 값을 표현하는 경우를 제외하고는 괄호를 사용하지 않는 것이 좋다.

 

if, if-else, if else-if else 문

if (condition) {
  statements;
}
if (condition) {
  statements;
} else {
  statements;
}
if (condition) {
  statements;
} else if (condition) {
  statements;
} else {
  statements;
}

 

for 문

for (initialization; condition; update) {
  statements;
}

 

while 문

while (condition) {
  statements;
}

 

do - while 문

do {
  statements;
} while (condition);

 

switch 문

switch (condition){
case ABC;
  statements;
case DFS;
  statements;
case XYZ;
  statements;
  break;
default;
  statements;
  break;
}

 

try-catch 문

try{
  statements;
} catch (ExceptionClass e){
  statements;
}

try{
  statements;
} catch (ExceptonClass e){
  statements;
} finally {
  statements;
}

 

8. 빈 공간

1. 한 줄 띄우기
   • 한 줄을 띄우고 코드를 작성하면, 논리적으로 관계가 있는 코드들을 쉽게 구분할 수 있기 때문에 코드의 가독성을 향상시킨다.
   • 다음과 같은 경우에는 두 줄을 띄어서 코드를 작성한다.
   1. 소스 파일의 섹션들 사이에서
   2. 클래스와 인터페이스의 정의 사이에서
   • 다음과 같은 경우에는 한 줄을 띄어서 코드를 작성한다.
   1. 메서드들 사이에서
   2. 메서드 안에서의 지역 변수와 그 메서드의 첫 번째 문장 사이에서
   3. 블록 주석 또는 한 줄 주석 이전에
   4. 가독성을 향상시키기 위한 메서드 내부의 논리적인 섹션들 사이에
2. 공백
   • 공백을 다음과 같은 경우에 사용된다.
   1. 괄호와 함께 나타나는 키워드는 공백으로 나누어야 한다.
   2. 메서드 이름과 메서드의 여는 괄호 사이에 공백이 사용되어서는 안된다. 이렇게 하는 것은 메서드 호출과 키워드를 구별하는데 도움을 준다.
   3. .을 제외한 모든 이항 연산자는 연산수들과는 공백으로 분리되어져야한다. 공백은 단항 연산자의 경우에는 사용해서는 안 된다.

9. 명명 규칙 ( Naming Convention)

• 명명 규칙, 즉 이름을 정하는 규칙은 프로그램을 더 읽기 쉽게 만들어 줌으로써 더 이해하기 쉽게 만들어 준다. 또한 식별자를 통해서 기능에 대한 정보도 얻을 수 있다.
• 카멜 스타일을 사용한다.

1. 패키지
   • 패키지의 이름은 최상위 레벨은 항상 ASCII 문자에 포함되어 있는 소문자로 쓰고, 가장 높은 레벨의 도메인 이름 중 하나이어야 한다.
   • 패캐지 이름의 나머지 부분은 조직 내부의 명명 규칙을 따르면 된다. 이러한 규칙을 따라 만들어진 이름은 디렉토리 구조에서 디렉토리 이름으로도 사용된다.
2. 클래스
   • 클래스 이름은 명사이어야 하며, 복합 단어일 경우 각 단어의 첫 글자는 대문자이어야 한다. 클래스 이름은 간단하고 명시적이 되도록 작성한다. 완전한 단어를 사용하고 두 문자어와 약어는 피하도록 하자
3. 인터페이스
   • 인터페이스 이름도 클래스 이름과 같은 대문자 사용 규칙을 적용해야 한다.
4. 메서드
   • 메서드의 이름은 동사이어야 하며, 복합 단어일 경우 첫 단어는 소문자로 시작하고 그 이후에 나오는 단어의 첫 문자는 대문자로 사용해야 한다.
5. 변수
   • 변수 이름의 첫 번째 문자는 소문자로 시작하고, 각각의 내부 단어의 첫 번째 문자는 대문자로 시작해야 한다. 변수 이름이 언더바 또는 달러 표시 문자로 시작하는 것이 허용되기는 하지만, 이 문자들로 시작하지 않도록 주의하다. 변수 이믈은 짧지만 의미 있어야 한다. 변수 이름의 선택은 그 변수의 사용 의도를 알아낼 수 있도록 의미적이어야 한다. 한 문자로만 이루어진 변수 이름은 임시적으로만 사용하고 버릴 변수일 경우를 제외하고는 피해야 한다.
6. 상수
   • 클래스 상수로 선언된 변수들과 ANSI 상수들의 이름은 모두 대문자로 쓰고 각각의 단어는 언더바로 분리해야 한다.

10. 좋은 프로그래밍 습관

1. 인스턴스 변수와 클래스 변수를 외부에 노출하지 말고 대신 접근을 제공
   • 인스턴스 변수 또는 클래스 변수를 합당한 이유없이 public 으로 선언하지 말아라. 인스턴스 변수들은 명시적으로 선언될 필요가 없는 경우도 많다.
   • 인스턴스 변수가 public 으로 선언되는 것이 적절한 경우는 클래스 자체가 어떤 동작을 가지지 않는 데이터 구조일 경우이다.
2. 클래스 변수와 클래스 메서드는 클래스 이름을 사용하여 호출
   • 클래스 변수 또는 클래스 메서드를 호출하기 위해서 객체를 사용하는 것은 피해야 한다. 대신에 클래스 이름을 사용해라.
3. 숫자는 바로 사용하지 말고 선언해서 변수 이름으로 접근
   • 숫자 상수는 카운트 값으로 for 루프에 나타나는 -1, 0, 1을 제외하고는 숫자 자체를 코드에 사용하지 말아라.
4. 변수에 값을 할당할 때 주의할 것들
   • 하나의 문에서 같은 값을 여러 개의 변수들에 할당하지 말아라. 이렇게 하면 읽기가 어렵게 된다.

원문 : Code Conventions for JavaTM Programming Language, Revised April 20, 1999

번역본 출처 : http://kwangshin.pe.kr/blog/java-code-conventions-%EC%9E%90%EB%B0%94-%EC%BD%94%EB%94%A9-%EA%B7%9C%EC%B9%99/