[Java] 코드 컨벤션 요약

Question

[Java] 코드 컨벤션 요약

yeoseon opened this issue 5 years ago · comments

Yun Yeoseon (Row) commented 5 years ago

Reference

자바 코딩 규칙

파일 구조

2000라인을 넘는 파일은 피한다.

자바 소스 파일

public 클래스는 파일에서 첫번째 클래스 또는 인터페이스여야 한다.

Class와 Interface 선언

변수는 접근성이 높은 것부터 선언한다.
문서화 주석은 /**.../
구현 주석은 /...*/

들여쓰기

4개의 빈칸을 들여쓰기 단위로 사용한다.
탭은 8개로 설정하는 것이 좋다.

한줄의 길이

한줄에 80자 이상 쓰는 것은 대부분 터미널과 툴에서 다룰 수 없기 떄문에 피한다.
문서화 주석은 한줄에 70자 이상을 가지지 않는다.

줄 나누기

하나의 식이 한줄에 들어가지 않을 때 다음 원칙으로 줄을 나눈다.

콤마 후에 두 줄로 나눈다.
연산자 앞에서 두 줄로 나눈다.
레벨이 낮은 원칙보다는 레벨이 높은 원칙에 따라 두 줄로 나눈다.
앞 줄과 같은 레벨의 식이 시작되는 새로운 줄은 앞줄과 들여쓰기를 일치시킨다.
더 복잡하게 나온다면 8개 빈 칸을 사용해 들여쓴다.

메서드 본문이 시작할 때 4칸을 사용하므로, 줄 나누기의 들여쓰기 경우는 구분을 위해 8칸 원칙을 사용한다.

주석

코드에 대한 개요, 코드로는 알 수 없는 추가 정보를 제공하기 위해 사용하여야 한다.
프로그램을 읽는 것과 이해하는 것에 관계된 정보만을 포함해야 한다.
코드 상에 이미 표현된 중복 정보는 피한다.
코드가 발전하면 필요 없는 주석은 제외하는 것이 방법이다.
주석이 부족하다고 느껴지고, 너무 많이 필요하다고 생각되면 코드 품질을 돌이켜본다.
별표를 사용해 사각형을 만드는 것은 피한다.

구현 주석

/* ... */
각 구현에 대한 추가적인 설명이 필요할 때
코드를 주석처리할 때

블록 주석

파일, 메서드, 자료구조, 알고리즘에 대한 설명을 제공
파일이 시작될 때와 메서드 전에 사용
메서드 안과 같은 다른 장소에서 사용될 수 있음.

/*
* 한줄을 비우고 여기에 작성한다.  
*/

한줄 주석

짧은 주석은 뒤따라 오는 코드와 동일한 들여쓰기를 하는 한 줄로 작성한다.
한줄에 다들어가지 않으면 블록 주석 형식을 따라야 한다.

        /* 한줄 주석 다음 코드와 동일한 들여쓰기 */
        ...

꼬리 주석

아주 짧은 주석
주석이 설명하는 코드와 같은 줄에 작성
실제 코드와 구분될 수 있도록 충분히 멀리 떨어뜨린다.

if (a == 2) { 
      return TRUE;                      /* 특별한 경우 */
}

줄 끝 주석

//
한줄 모두를 주석처리 하거나, 한 줄의 일부분을 주석처리 해야할 경우
연속되는 줄에 이 주석을 사용하지 않는다.
어떤 코드의 일부분을 처리하기 위해서는 허락된다.

문서화 주석

/** ... */
자바에서만 사용된다.
javadoc 툴을 사용하면 HTML 파일을 자동으로 만들 수 있다.
구현된 코드와 상관 없는 코드의 명세 사항을 포함한다.

다음과 같은 5가지를 설명한다.

자바 클래스
인터페이스
생성자
메서드
필드

선언

한 줄에 하나의 선언만 하는 것이 좋다.
여러 선언의 경우, 들여쓰기를 통해 변수명을 맞춰주는 것도 좋다.

초기화

지역 변수는 선언시 초기화하는 것이 좋다.
다른 계산에 의해 결정되는 경우는 안해도 된다.

배치

선언은 블록의 시작에 위치한다.
변수를 사용할 때까지 선언을 미루지 않는다.
한번 선언한 변수를 블록 안에서 다시 선언하지 않는다.

클래스와 인터페이스의 선언

메서드 이름과 메서드 파라미터 리스트의 시작인 괄호 "(" 사이에는 빈 공간이 없도록 한다.
여는 중괄호 "{"는 클래스/인터페이스/메소드 선언과 동일한 줄의 끝에 사용한다.
닫는 중괄호 "}"는 여는 문장과 동일한 들여쓰기를 한 새로운 줄에서 사용한다.
각 메서드들 사이에는 한 줄을 비우자.

문 (Statements)

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

복합문

중괄호로 둘러싸여진 문들의 리스트를 포함하는 문

둘러싸인 문들은 복합문보다 한 단계 더 들여쓴다.
여는 중괄호 "{"는 복합문을 시작하는 줄의 마지막에 위치한다.
닫는 중괄호 "}"는 새로운 줄에 쓰고, 복합문 시작과 같은 들여쓰기 한다.
중괄호 들이 if / for 문과 같은 제어구조의 일부로 사용될 때는, 중괄호로 모두 닫아줘야 한다.

return 문

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

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

항상 중괄호를 사용하여 에러 상황을 피한다.

for 문

for 문의 초기화 또는 update 구문에서 "," 연산자를 사용할 때, 3개 이상의 변수를 사용하는 것은 피한다.
필요하다면 for 문 이전에 문을 분리시켜 사용하거나, 마지막에 문을 분리시킨다.

switch 문

모든 Case를 수행해야 하는 경우에는 break 문을 무조건 사용해야 한다.
default 문을 포함해야 한다.

try-catch 문

성공 적으로 완료되던, 에러가 발생하던 상관 없이 실행해야하는 부분이 있을 때 finally를 사용한다.

빈 공간

한 줄 띄우기

한줄을 띄우면 코드 가독성이 좋아진다. 다음의 경우 띄어준다.

메서드 사이
메서드 안에서의 지역변수와 메서드의 첫 번째 문장 사이
블록 주석 또는 한줄 주석 이전
가독성 향상을 위한 내부 논리적인 섹션 사이

다음과 같은 경우는 두줄을 띄어준다.

소스파일의 섹션
클래스와 인터페이스의 정의 사이

공백

메서드이름과 메서드 여는 괄호 사이에는 공백이 사용되어서는 안된다.
닫는 괄호와 함수 중괄호 시작 사이에는 공백을 사용한다.
인자 리스트에서 콤마 이후에 나타나야 한다.
.을 제외한 모든 이항 연산자는 연산수들과 공백으로 분리되어야 한다.
단항 연산자(++)의 경우는 사용하지 않는다.
for 문 내의 3개의 식은 공백으로 구분해야 한다.
Cast 또한 공백으로 구분해야 한다.

명명 규칙

Packages

최상위 레벨은 항상 소문자로 쓰고, 가장 높은 레벨의 도메인 이름 중 하나여야 한다.
패키지 이름의 나머지 부분은 조직 내부의 명명규칙을 따른다.

Classes

명사여야 한다.
복합 단어의 경우 각 단어의 첫글자는 대문자.
간단하고 명시적으로 작성
완전한 단어를 사용하고, 두 문자어와 약어는 피한다.

Interfaces

인터페이스 이름도 클래스 이름과 같은 대문자 규칙을 적용한다.

Methods

동사여야 한다.
복합 단어의 경우 첫 단어는 소문자로 시작한다.

Variables

변수 이름의 첫번째 문자는 소문자여야 한다.
언더바 또는 달러 표시 문자로 시작하는 것이 허용 되기는 하지만, 사용하지 말자.
짧지만 의미있게 짓는다.
변수의 사용 의도를 알 수 있도록 의미적으로 짓는다.
한문자로만 이루어진 변수는 암시적으로만 사용하고 버릴 변수를 제외하고는 피한다.
임시 변수의 이름은 integer는 i,j,k,m,n 을 사용하고 character는 c,d,e를 사용한다.

Constants

클래스 상수로 선언된 변수들과 상수들의 이름은 모두 대문자로 쓰고 각 단어는 언더바 ("_")로 분리한다.
ANSI 상수 사용은 디버깅을 위해 피한다.

좋은 프로그래밍 습관

인스턴스 변수와 클래스 변수를 외부에 노출하지 말고, 접근을 제공한다.

합당한 이유없이 public으로 선언하지 말자.
인스턴스 변수가 public으로 선언되는 것이 적절한 경우는 클래스 자체가 어떤 동작을 가지지 않는 데이터 구조일 경우이다.

클래스 변수와 클래스 메서드는 클래스 이름을 사용하여 호출

클래스(static) 변수 또는 클래스 메서드를 호출하기 위해 객체를 사용하는 것은 피한다. 클래스 이름을 사용해라.

classMethod();                   // good  
Aclass.classMethod();      // good  
anObject.classMethod(); // bad

숫자는 바로 사용하지 않고 선언해서 변수명으로 접근한다.

for 루프에 나타나는 값을 제외하고는 숫자 자체를 사용하지 않는다.

변수에 값을 할당할 때 주의할 점

하나의 문 안에서 같은 값을 여러 개의 변수들에 할당하지 않는다.

fooBar.fChar = barFoo.Ichar = 'c';      // bad

비교 연산자와 혼동되기 쉬운 곳에 할당 연산자를 사용하지 말자.

실행시 성능 향상을 위해 할당문 안에 또 다른 할당문을 사용하지 말자.

그 외 신경써야 할 것들

괄호

연산자 우선순위 문제를 피하기 위해 복합 연산자의 경우는 자유롭게 괄호를 사용한다.

반환값

프로그램의 구조와 목적이 일치해야 한다.

조건 연산자 '?' 이전에 나오는 식

삼항 연산자에서 ? 이전에 이항 연산자를 포함하는 식이 있는 경우에는 꼭 괄호를 사용한다.

(x >= 0) ? x : -x;

메소드 순서 (next-step/java-ladder#345 (comment) 참고)

public을 제일 위에 모아두고, private을 사용되는 순서로 그 아래 모아두는 방법
public과 public에서 사용되는 private을 그아래 순차적으로 나열하는 방법