코딩컨벤션 작성하기

여러 명의 개발자들이 함께 협업할 때 코드의 일관성을 유지하는 것은 매우 중요하다. 

서로 다른 코딩 스타일은 유지보수를 어렵게 하고, 가독성을 떨어뜨리기때문이다. 따라서 프로젝트를 시작하기 전에 나만의 코딩 컨벤션을 작성하는것이 좋다고 생각한다. 명확한 기준이 없는 상황에서는 코드 스타일이 일관되지 않아 유지보수가 어려워지기 때문이다. 

그래서 오늘은 나만의 간단한 코딩컨벤션을 구글 가이드 문서를 참고하여 작성해보려고한다.  

 

코딩컨벤션

: 일관된 코딩 스타일과 가이드라인을 정의하여 코드 가독성과 유지보수성을 향상시키는 규약이다. 팀원들 간의 코드 일관성을 유지하고 코드 품질을 향상시키기 위해 사용된다.

 

 

---

# 소스 파일 구조

소스 파일의 구조는 아래와 같이 구성된다. 

 

1. 라이센스 또는 저작권 정보 

 

2. Package 구문

 

3. Import 구문 

• static imports 구문을 작성 후 non-static imports문을 작성한다. 
• static imports 문에만 와일드 카드를 허용한다.
• static imports와 non-static imports가 모두있는 경우 하나의 빈 줄이 두 블록을 구분한다. 

 

4. 하나의 최상위 Class

• 소스 파일마다 각자의 최상위 클래스가 존재
• 상수, 멤버 변수(필드), 생성자, 메서드 순으로 작성
• 메서드는 기능 및 역할별로 분류하여 작성한다. 
• 한 줄에 여러 필드를 선언하지 않고, 하나의 필드만을 다룬다. 

 

package who.study.convention;

import static java.util.Collections.sort;
import static java.util.Collections.shuffle;

import java.util.List;
import java.util.ArrayList;

public class ExampleClass {

    public static void main(String[] args) {
		
        // 상수
        private static final int MAX_VALUE = 100;
        
        // 멤버 변수
        private String name;
        private int age;
        
        // 생성자
        public ExampleClass(String name, int age) {
            this.name = name;
            this.age = age;
    	}
        
        // 메서드 - 기능 및 역할별로 분류
    	public void printInfo() {
            System.out.println("Name: " + name);
            System.out.println("Age: " + age);
    	}


    }

}

 

 

---

 

 

# 코드 레이아웃 

 

1.  들여쓰기

• 들여쓰기는 4개의 space를 사용한다. 
• IDE의 들여쓰기 설정을 이용하자. 
• 클래스, 메서드, 제어문 등의 코드 블럭이 생길 때 마다 1단계를 더 들여쓴다. 

 

2.  띄어쓰기 및 공백

• 연산자 앞뒤로 띄어쓴다. 
• 클래스, 메서드, 제어문 등의 코드 블럭이 생길 때마다 1단계를 더 들여쓴다.
• 중괄호의 시작 전, 종료 후 공백을 삽입한다. 
• 대괄호 뒤에 공백을 삽입한다.
• 콤마/구분자 세미콜론 뒤에 공백을 삽입한다. 

# 중괄호 예시
public void printWarnMessage(String line) {
    if (line.startsWith(WARN_PREFIX)) {
        ...
    } else {
        ...
    }
}

# 대괄호 예시 
int[] masks = new int[] {0, 1, 1};

# 콤마 구분자 예시
for (int i = 0; i < length; i++) {
    display(level, message, i)
}

 

 

 

3.  줄바꿈

• 줄바꿈 이후 이어지는 줄에서는 최초 시작한 줄에서보다 적어도 1단계의 들여쓰기를 더 추가한다.

AbstractAggregateRootTest.AggregateRoot proxyAggregateRoot = 
	em.getReference(AbstractAggregateRootTest.AggregateRoot.class, aggregateRoot.getId());

 

 

4. 빈줄

• 메서드의 선언이 끝난 후 다음 메서드 선언 시작 전 빈줄을 삽입힌다. 

public void setId(int id) {
    this.id = id;
}

public void setName(String name) {
    this.name = name;
}

 

 

 

5. 중괄호 

• 중괄호는 K&R 스타일을 따른다. 
• 여는 중괄호는 제어문과 같은 라인에서 사용한다. 
• 닫는 중괄호는 줄바꿈 후 사용한다. 
• 다는 중괄호와 같은 라인에 else, catch, finally, while 등을 선언한다. 

 

6. 변수 초기화 

• 변수가 사용되는 곳의 가까운 위치에 변수를 선언한다. 

 

 

 

---

 

 

# 특정 구조 

 

1. Enum Class

• Enum 클래스 내부에서 각 상수 뒤 콤마 뒤에 줄바꿈을 한다.

private enum Color {
    Red, 
    Yellow,
    Blue
}

 

 

2. switch 문 

• switch 블록 내부의 case 및 default 블록은 switch 와 동일한 라인에 작성한다. 
• break 키워드는 case 블록 보다 1단계 들여쓰기를 한다. 
• 항상 default를 작성하여 처리되지 않은 경우에 대비한다. 

switch (variable) {
    case value1:
        // code block for value1
        break;
    case value2:
        // code block for value2
        break;
    default:
        // code block for default
}

 

 

3. try ~ catch

• try, catch, finally 키워드 뒤에 중괄호를 사용한다. 
• catch 블록은 구체적인 예외 타입순으로 위에서 아래 순서로 나열한다. 
• catch 블록에서 아무런 이벤트가 없는 경우 이유에 대하여 주석으로 작성해두어야 한다.

try {
    // 예외가 발생할 수 있는 코드
    // ...
} catch (IOException e1) {
    // IOException 처리 코드1
} catch (ExceptionType2 e2) {
    // 예외 처리 코드2
} finally {
    // 항상 실행되어야 하는 코드 (예외 발생 여부와 상관없이)
}

 

 

4. Annotations

• 클래스, 메서드, 생성자에 선언되는 어노테이션은 한 줄에 하나의 어노테이션만 선언된다. 

@AnnotationName
@AnotherAnnotation
public class ExampleClass {

    @Override
    public void methodName() {
        // code here
    }

    @SuppressWarnings("unchecked")
    public void anotherMethod() {
        // code here
    }
}

 

 

 

---

 

 

# 네이밍



모든 식별자에 해당하는 공통적인 규칙

• 식별자는 ASCII 문자와 숫자만 사용하며 _를 사용하기도 한다. 

 

패키지

• 패키지명은 모두 소문자로 이루어지며 연속 된 단어는 밑줄 없이 함께 연결되어 작성된다. 

 

클래스

• UpperCamleCase 형식을 따른다. 
• 일반적으로 명사 또는 명사구가 사용된다. (Ex. SomeClass, ProductClass)
• 테스트 클래스명은 테스트 대상인 클래스 명으로 시작되고 끝에 Test를 붙인다. (Ex. SomeClassTest, ProductClassTest)
• 인터페이스 클래스에도 똑같은 규칙을 적용한다. 

// 대상 클래스
public class Calculator {

    public int add(int a, int b) {
        return a + b;
    }

    public int subtract(int a, int b) {
        return a - b;
    }
    
    public void saveInfo() {
    }
}

// 테스트 클래스
public class CalculatorTest {

    public void testAdd() {
        Calculator calculator = new Calculator();
        int result = calculator.add(3, 5);
        // assert result
    }

    public void testSubtract() {
        Calculator calculator = new Calculator();
        int result = calculator.subtract(8, 3);
        // assert result
    }
}

 

메서드

• lowerCamelCase 형식을 따른다. 
• 일반적으로 동사 또는 동사구로 작성된다. (Ex. sendMessage, add, stop)
• JUnit 테스트 메서드 이름에 밑줄이 표시되어 이름의 논리적 구성 요소를 구분할 수 있다.

 

필드

• lowerCamelCase 형식을 따른다.
• 한줄에 하나의 필드만 선언한다. 
• 명사 또는 명사구로 작성된다. (Ex. computedValues, index)
• 한글자로 된 이름을 사용하지 않는다. 

 

파라미터

• lowerCamelCase 형식을 따른다.
• 예약어를 파라미터명으로 사용하지 않아야 한다. 

public class Calculator {

    // 메서드 정의: 두 개의 정수를 더하는 메서드
    public int add(int operand1, int operand2) {
        return operand1 + operand2;
    }

    public static void main(String[] args) {
        Calculator calculator = new Calculator();

        // 메서드 호출: 두 정수를 더하는 메서드 호출
        int result = calculator.add(5, 3);
        System.out.println("덧셈 결과: " + result);
    }
}

 

상수명

• CONSTANT_CASE 형식을 따른다. 
• 모두 대문자로 이루어져 있고, 밑줄로 각 단어를 구분한다. 

// Constants
static final int NUMBER = 5;
static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");
static final ImmutableMap<String, Integer> AGES = ImmutableMap.of("Ed", 35, "Ann", 32);
static final Joiner COMMA_JOINER = Joiner.on(','); // because Joiner is immutable
static final SomeMutableType[] EMPTY_ARRAY = {};
enum SomeEnum { ENUM_CONSTANT }

 

 

---

 

 

# 주석

• 주석문 전후에는 공백을 삽입한다. 
• 각 상황별 주석은 아래와 같이 사용한다. 
• 추후 개선이 필요한 부분에는 TODO 주석을 작성한다. 
• 주의가 필요한 곳에는 꼭 주석을 작성하도록 한다. 

# 명령문과 같은 주석을 사용 할 때 
System.out.println(true) // 주석 기호 앞뒤로 고앱ㄱ을 추가한다. 

# 코드에 대한 설명이나 주석 내용을 여러줄로 작성 할 때 
/** 
 * 텍스트가 여기에 작성됩니다. 
 * 그 다음줄에 대한 내용을 작성한다. 
 */ 

# 한줄로 주석을 작성할 때 
/* 주석 내용 앞뒤로 공백을 추가 후 작성한다. */

# TODO 주석 
public int add(int a, int b) {
    // TODO: 예외 처리 추가
    return a + b;
}

 

 

 

---

 

 

 

참고

• Google Java Style Guide 원본
• Google Java Style Guide 번역본
• 쭈미로운 생활 - 자바 코딩 컨벤션