프로젝트 컨벤션 제안

[queuedq]

관련 이슈: #21

현재 프로젝트의 각종 컨벤션 및 새로 제안하고자 하는 컨벤션은 다음과 같습니다.

브랜치

• 브랜치 이름으로 feat/#issue/feature-name,feature/#issue/feature-name 이 혼용되고 있습니다.
  • 긴 이름은 error-prone 하다는 이유를 들어, 가장 단순한 feature-name을 사용할 것을 제안합니다.
• 지난 중간 점검 회의 때 정한 사항인데, 한 풀 리퀘스트에 여러 가지 기능이 복합적으로 들어갈 경우 다음과 같이 브랜치를 쪼개서 풀 리퀘스트를 날리기로 했습니다.
  • 각 브랜치를 dev에서 따고, dev <- main-feature, dev <- sub-feature-1 과 같은 식으로 여러 개의 독립적인 풀 리퀘스트를 만듭니다. main-feature에서는 다른 풀 리퀘스트가 완료되기 전에도 main-feature <- sub-feature-1 과 같은 식으로 미리 머지를 해서 코드를 계속 작성할 수 있습니다.
  • 완전히 독립적인 기능들에 대해서는 위와 같은 방법이 통하지만, 종속 관계가 있는 기능에 대해서는 위와 같은 방법을 적용하기 어렵습니다. (sub-feature가 main-feature에 의존하는 경우)
  • 새로 제안하고자 하는 브랜칭 규칙은 다음과 같습니다. 우선 독립적인 기능들은 위 규칙을 적용하며, 그렇지 않은 경우에는 dev <- main-feature, main-feature <- main-feature/sub-feature-1 과 같은 식으로 main-feature에 의존적인 기능의 브랜치를 /로 구분하여 이름짓고 dev가 아닌 main-feature 로 풀 리퀘스트를 날립니다. 이는 위에서 제안한 단순한 브랜치 네이밍과도 시너지가 납니다.

코드 컨벤션

• 기본적으로 IntelliJ IDEA에서 제안하는 코드 포매팅과 Google Java Style Guide 를 따릅니다.

공백 문자

• 인덴트는 기본 스페이스 4칸이고, 만약 한 줄에 적을 수 있는 코드를 가독성의 이유로 여러 줄로 쪼갤 경우 스페이스 8칸을 사용합니다.
• 메소드 정의, 조건문, 반복묵, 함수 호출, 코멘트의 경우 다음과 동일한 포매팅을 사용합니다.

  public User getUser(int id) {
      if (condition) {
          doSomething();    // some comment
      }
  
      for (User user : users) {
          doSomething();
      }
  }

• 한 줄에 적을 수 있는 조건문은 한 줄에 적어도 무방하지만, 중괄호는 어떤 경우에도 생략하지 않습니다.

명료성

• 메소드는 이름과 함수 시그니처 (인자, 리턴 타입)을 보고 어떤 역할을 하는지 단번에 알아볼 수 있도록 작성해 주세요.
• 중요한 메소드는 앞에 documentation comment를 달아 어떤 역할을 하는지 작성해 주세요. @param, @return 은 반드시 작성하지 않아도 됩니다.

간결성

• 각 줄은 120자를 넘지 않습니다.
• 타입을 추론(infer)할 수 있는 경우 최대한 간결하게 작성합니다. 아래 예시에서 우측 <> 사이에 타입이 들어가지 않는 점을 참고하세요.

  Map<String, User> users = new HashMap<>();

OOP

• 변수에는 보다 일반적인 타입을 사용합니다. e.g. ArrayList 대신 List, HashMap 대신 Map. 물론, 변수에 값을 대입할 때는 구체적인 구현을 넣어 줘야 합니다.

  Map<String, User> users = new HashMap<>();

• C 스타일 배열 (e.g. String[]) 은 커맨드라인 인자를 받기 위한 Main을 제외한 어떤 곳에서도 사용하지 않습니다. 대신 더 기능이 다양한 List를 사용합니다.
• 대부분의 클래스의 필드는 private하게 작성하며, getter를 사용합니다.

[jaehwan1912]

확인했습니다.
rankingservice refactoring에도 바로 반영해보도록 하겠습니다!

[queuedq]

추가로 테스트 이름 컨벤션이 필요합니다.
현재 테스트 이름은 testMethodName 과 같은 형식으로 되어 있는데, 이는 유닛 테스트가 메소드가 아닌 behavior를 테스트한다는 철학과 맞지 않는다고 생각합니다.
참고: https://dzone.com/articles/7-popular-unit-test-naming