Java

Java contribution guide

일반

• String placeholder 작업에 대해 .formatted()를 사용합니다. 가독성 및 추후 변경에 유리합니다.

• 여러 개의 매개변수를 포함하는 메서드는 각 매개변수 마다 줄 바꿈을 해야 합니다. (단, 놔두는 것이 가독성에 더 좋을 것으로 판단되는 경우는 예외)

• 삼항 연산자는 가독성을 위해 조건마다 줄 바꿈이 되어야 합니다. 최종적으로, 3줄로 보여야 합니다.

• return 문을 포함하고 있는 줄은 다른 줄과 구분되어야 합니다. 다른 구문과 함께 존재할 경우 1개의 줄 바꿈을 포함해야 합니다.

• 주석은 가독성을 위해 // 옆에 1개의 띄어쓰기가 포함되어야 합니다.

• 중괄호 밑에 포함된 구문이 한 줄 일 경우 들여쓰기를 지켜 생략 하는 것이 가독성에 좋습니다. (단, 안전성 등의 측면에서 반론이 있을 수는 있습니다.)

• 생성자 오버로딩을 하는 경우 파라미터 갯수 대로, 제일 많은 파라미터를 가진 생성자가 맨 밑으로 위치합니다. 이는 메서드 오버로딩 에서도 동일합니다.

• Collection의 경우 생성자 초기화가 아니라 필드 초기화를 우선으로 합니다.

• 두문자어 등 줄임말에도 CamelCase 를 적용합니다. 예) SigItemAPI -> SigItemApi

어노테이션

• 어노테이션은 메서드 위에 위치해야 합니다. 메서드를 포함하는 줄에는 메서드의 이름 및 매개변수만 존재하는 것이 가독성에 좋습니다.

• 어노테이션은 긴게 밑으로 갑니다. 단, 중요한 어노테이션의 경우 순서를 무시할 수 있습니다.

• Block 작업에 대해 @Blocking을, Async 작업에 대해 @NonBlocking을 달 것을 권장합니다.

• 주석 대신 org.jetbrains.annotations의 어노테이션 들을 사용합니다.

NotNull, Nullable

• @NotNull, @Nullable은 org.jetbrains.annotation 라이브러리의 것을 사용합니다.

• 필드 및 함수의 리턴 값에는 @Nullable 일 때만 어노테이션을 붙입니다. (그러나 있는 @NotNull을 지우진 않습니다.)

• 함수의 매개변수에 @NotNull과 @Nullable을 반드시 붙입니다.

• 함수의 지역변수에는 @NotNull, @Nullable을 붙이지 않습니다.

• 사용 시 불필요한 경고가 많이 추가될 것으로 예상되는 경우에도 어노테이션을 추가하는 것이 장기적으로 좋습니다.

Example

@Getter
public class Example {
  private final String data; // 필드는 @NotNull로 간주합니다.
  @Nullable // @Nullable 한 경우 반드시 표기되어야 합니다.
  private final String nullValue = null;
  
  public Example(@NotNull String data) { // 생성자
    this.data = data;
  }
  
  // 리턴 값은 @NotNull로 간주합니다.
  public String append(@NotNull String toAppend) { // 매개변수
    String nowData = data; // 지역변수는 어노테이션을 가지지 않습니다.

    return nowData + toAppend;
  }
  
  @Nullable // @Nullable 한 경우 반드시 표기되어야 합니다.
  public String getIfEquals(@NotNull String toCompare) {
    if (toCompare.equals(data))
      return data;
    else
      return null;
  }
  
}

JavaDocs

• API 용도의 클래스 및 메서드 에는 JavaDocs를 예제 코드와 함께 다는 것을 추천합니다.

• 예제 코드는 <pre>{@code 내용}</pre>를 사용합니다.

유효성 검사

• 가능한 경우 Hibernate Validator를 우선으로 사용합니다.