[프리코스 1주차] 자바 코딩 컨벤션(해설)

[❓자바 코딩 컨벤션 왜 지켜야 하는가? ]

예를 들어, 대학생 시절에 조별과제 ppt를 만들기 위해 5명이 모였다고 가정을 합니다.

ppt를 5분할 해서 각자 맡을 파트를 정하고, 3일 뒤에 각자 ppt를 완성하여 만났습니다. 그런데, ppt의 배경 색, 글자 크기와 색등을 통일하지 않고 각자 취향껏 만들어왔습니다. 이 상태로 ppt를 합친다면 좋은 점수를 못 받을 것은 분명합니다.

 

코딩도 똑같습니다. 여러 개발자가 협업하는 과정에서 내가 작성한 코드를 다른 개발자가 작업하거나, 반대로 다른 개발자가 작업한 코드를 내가 작업할 때도 있습니다. 이 때, 자바 코딩 컨벤션을 통일해서 코드를 작성했다면 어려움 없이 상대방의 코드를 읽고, 추가 작업을 할 수 있습니다. 

 

즉, 자바 코딩 컨벤션는 개발자들의 협업을 원할하게 하기 위함입니다.

 

1주차 프리코스 요구사항 중 하나인 자바 코딩 컨벤션에 대해 공부할 겸 정리해봤습니다. 링크된 글과 같이 보시길 추천합니다.

[❗이 내용은 구글 코딩 컨벤션에서 제공하는 글 중 모르는 부분만을 기준으로 해설(표시 : → )함을 미리 알려드립니다.]

2. 소스 파일 기본 사항

2.3.2 특수 이스케이프 시퀀스

특수 이스케이프 문자들( \b, \t, \n, \f, \r, ", '과 \)은 해당 진수(\012) 또는 유니 코드(\u000a)이스케이프 대신 해당 문자가 사용된다.

 

→ 우리가 흔히 아는 줄바꿈 문자인 \n은 특수 이스케이프 문자이다. 줄바꿈 문자를 진수로 나타내면 \012이고, 유니코드로 나타내면 \u000a이다. 줄바꿈 문자를 진수나 유니코드로 나타내지 말고,  특수 이스케이프 문자를 쓰자.

 

✅이스케이프 (escape) 문자 표

이스케이프는 역슬래시(' \ ')로 시작하는 특수한 문자로 코드에서 특정 문자를 나타내기 위해 사용한다.

특수 이스케이프 문자		예시	출력 결과
\b	백스페이스	System.out.print ( "Hello, World! ")  → Hello, World! 를 출력 System.out.print ( "\b\b\b\b\b\b\b" ) → 7번 백스페이스로 커서를 앞으로 옮김 System.out.print ( "Java!" ) → Java! 를 출력	Hello, Java!
\t	탭	System.out.print ( "이것은\t탭 입니다" )	이것은    탭 입니다
\n	줄 바꿈	System.out.print ( "이것은\n새로운 줄입니다." )	이것은 새로운 줄입니다.
\r	캐리지 리턴	System.out.print ( "안녕하세요\r반갑습니다." ) → 안녕하세요 위에 반갑습니다를 쓴다	반갑습니다.
\'	작은 따옴표	System.out.print ("작은따옴표 \'이다." )	작은따옴표 '이다.
\"	큰 따옴표	System.out.print ("큰따옴표 \"이다." )	큰따옴표 "이다.
\\	역슬래시	System.out.print ("역슬래시 \\이다." )	역슬래시 \이다.

2.3.3 Non-ASCII 문자

Non-ASCII 문자의 경우 실제 유니 코드 문자 (예 : ∞)또는 동등한 유니 코드 이스케이프 (예 : \u221e) 가 사용됩니다. 유니 코드가 문자열 리터럴 및 주석 외부에서 이스케이프하는 것은 권장되지 않지만 코드를 더 쉽게 읽고 이해할 수 있는 방법에 따라 사용할 수도 있다.

 

→ Non-ASCll(ASCII 코드 외의 다른 문자)들을 코드로 쓸 때, 유니코드를 사용할 수 있지만 유니코드만을 쓰기에는 가독성이 좋지 않으니 가독성을 위해 주석이나 Non_ASCII를 써도 괜찮다. 

3. 소스 파일 구조

3.3.4 클래스에는 static import를 하지 않는다.

static 중첩 클래스에는 static import가 사용되지 않습니다. 그들은 일반적인 import를 사용합니다.

 

→ 이렇게 중첩 클래스인 mode는 static import를 하지 않습니다.

public class Car {
	...
    static class mode {

3.4.2 클래스 내용 순서

클래스의 멤버 및 이니셜 라이저에 대해 선택한 순서는 이해하는데 큰 영향을 미칠 수 있습니다. 그러나 이를 수행하는 방법에 대한 정해진 방법은 없습니다.

*이니셜 라이저 : 초기화 블럭으로, 예시로는 생성자의 초기화 블록이 있다. 

다른 클래스는 다른 방식으로 내용 순서를 정할 수 있습니다. 중요한 것은 각 클래스가 몇 가지 논리적 순서를 사용한다는 것입니다. 이 순서는 관리자가 요청하면 설명 할 수 있어야 한다.

 

→  새로운 메서드가 클래스 끝에 습관적으로 추가되었다면 논리적 순서가 아닌 "추가 된 날짜 별 시간순" 순서로 정한 것이라고 설명 할 수 있어야 한다.

4. Formatting

4.5.2 연속 줄을 최소 +8 공백 들여 쓰기 (우테코 스타일)

줄 바꿈시 첫 번째 줄 (각 연속 줄 ) 뒤의 각 줄 은 원래 줄에서 적어도 +8만큼 들여 쓰기됩니다.

 

→  람다식의 메서드체이닝을 할 때가 연속 줄이다. 연속 줄은 커서로 부터 스페이스 바를 8번 누르면 된다. 

커서를 8번 스페이스 하면 됨

4.7 그룹화 괄호 : 권장

선택적 그룹화 괄호는 작성자와 검토자가 코드가 없으면 코드가 잘못 해석 될 가능성이 없으며 코드를 읽기 쉽게 만들지 않았다는 데 동의하는 경우에만 생략됩니다. 모든 독자가 자바 연산자 우선 순위 테이블이 있다고 가정하는 것은 옳지 않다. 우선순위가 명확해도 괄호로 감싸라❗️

 

→ 논리 연산자와 대입 연산자가 있으면 논리 연산자가 당연히 먼저 실행되는 것은 명백하지만, 모두가 이를 알고 있을 것이라 생각하지 말고 먼저 실행되는 것들끼리 ( )를 이용해서 묶어주기

4.8.3.1 배열 이니셜 라이저 : "block-like"

모든 배열 이니셜 라이저는 선택적 으로 "block-like construct"인 것처럼 형식화 될 수 있습니다.
다음의 경우 모두 가능하다.

 

→ 아래 예시 다 가능

new int[] {           new int[] {
  0, 1, 2, 3            0,
}                       1,
                        2,
new int[] {             3,
  0, 1,               }
  2, 3
}                     new int[]
                          {0, 1, 2, 3}

4.8.4.2 Fall-through : 주석

Switch 블록 내에서 각 문 그룹 중 하나 (break, continue, return또는 발생한 예외)가 돌연 중료되서나, 다음 구문으로 넘어가게 적을 수 있다. 여기에는 주석을 달 수 있다. (일반적으로 // fall through). 이 특수 주석은 스위치 블록의 마지막 명령문 그룹에는 필요하지 않습니다.

 

→ 원래는 input에 맞는 case만실행되어야 하는데, fall through 주석이 있는 케이스는 다음 케이스까지 실행한다는 의미이다. 예시에서는 case2가 실행되면 case 3도 실행된다는 의미.

그러나, break와 같이 switch를 빠져나가는 구문이 있는 case에는 다음에 실행할 case가 없어서 fall through가 필요가 없다.

  switch (input) {
  case 1:
  case 2:
    prepareOneOrTwo();
    // fall through
  case 3:
    handleOneTwoOrThree();
    break;
  default:
    handleLargeNumber(input);
}

4.8.7 Modifiers (접근 제한자)

클래스와 멤버의 접근 제한자 목록

public protected private abstract default static final transient volatile synchronized native strictfp

5. Naming

5.3 카멜 케이스 : 정의 된 단어들에 대하여

두문자어 또는 "IPv6"또는 "iOS"와 같은 비정상적인 구조가있는 경우와 같이 영어 구를 낙타 대문자로 변환하는 합리적인 방법이 여러 가지 있습니다. 예측 가능성을 높이기 위해 Google 스타일은 다음과 같은 (거의) 결정론적 체계를 지정합니다.

 

산문 형태의 이름으로 시작:  →  1~4번은 Google 이 정한 규칙을 말한다

1. 구를 일반적인 ASCII로 변환하고 어포스트로피를 없앤다. 예를들어 Müller's algorithm은 Muellers algorithm로 변환.
2. 결과를 단어로 나누고 남은 공백과 구두점 (일반적으로 하이픈)으로 나눈다.
   • 추천: 어떤 단어가 이미 전통적인 캐멀 케이스방식이 쓰인다면 이것을 구성하는 부분들로 나눈다. (예를들어 "AdWords"를 "ad words"로). "IOS"는 캐멀케이스가 아니다. 이 부분은 어떠한 약속에도 위배되므로 적용되지 않는다.
   • → 캐멀케이스는 낙타의 등처럼 붙일 단어의 첫 앞 글자를 대문자로 만드는 것. ex) use number 는 useNumber로 make coffee는 makeCoffee 
3. 이제 모두 lowercase로 바꾸고 (심지어 두음문자도) 그리고 첫 번째 글자를 대문자로 바꾸는데 그 바꾸는 문자들은:
   • 각 단어
   • 각 단어지만 첫 번째를 제외, 첫 번째는 lowercase
4. 이제 하나로 조합한다.

→ 고유명사나 신문 같은거 보면 대문자로 할지 소문자로 할지 애매한 것들을 띄어쓰기가 허용되지 않는 코딩에 어떻게 적용할지를 정한 규칙이라 생각하자.

산문 형태	옳은 예시	틀린 예시
"XML HTTP request"	XmlHttpRequst	XMLHTTPRequest
"new customer ID"	newCustomerId	newCustomerID
"inner stopwatch"	innerStopwatch	innerStopWatch
"support IPv6 on iOS?"	supportsIpv6OnIos	supportsIPv6OnIOS
"YouTube importer"	YouTubeImporter YoutubeImporter  → 권장하지는 않음

*모호하게 하이픈이 있는 단어가 몇개 있다. 예를들어, "nonempty" 나 "non-empty"는 둘 다 맞다. 그래서 메소드 이름이 checkNonempty나 checkNonEmpty 둘다 맞다.

6. 프로그래밍 실습

6.1 @Override: 항상 사용

@Override가 허락 될 때마다 주석 으로 표시됩니다 .
여기에는 슈퍼 클래스 메소드를 재정의하는 클래스 메소드, 인터페이스 메소드를 구현하는 클래스 메소드, 슈퍼 인터페이스 메소드를 재 지정하는 인터페이스 메소드가 포함됩니다.

예외 : 부모 메서드가 @Deprecated인 경우 @Override 생략 할 수 있다.

6.2 예외 잡기 : 생략하지 말 것

아래 명시되있는 것말고 예외를 잡고 아무것도 안하는 것은 거의 있을 수 없다. (전형적인 반응은 로그를 남기는 것 혹은 불가능하다고 간주되면 AssertionError로 다시 던져준다)

정말로 캐치블럭에서 아무것도 하지 않는것이 정당하다면 주석을 남기는것으로 정당화한다.

try {
  int i = Integer.parseInt(response);
  return handleNumericResponse(i);
} catch (NumberFormatException ok) {
  // 숫자가 아니다; 괜찮으니 그냥 넘어간다
}
return handleTextResponse(response);

예외: 테스트에서 예외를 잡는 부분은 expected, 혹은 expected로 시작하는 이름을 지으면서 무시할 수 있다. 다음 예제는 테스트에서 예외가 나오는게 확실한 상황에서 사용되는 대중적인 형식으로 주석이 필요가 없다.

try {
  emptyStack.pop();
  fail();
} catch (NoSuchElementException expected) {
}

7 Javadoc

7.1.3 블록 태그

블록 태그는 @param, @return, @throws, @deprecated 로 네 가지 유형이 있다. 블록 태그가 한 줄에 들어가지 않으면 연속 줄은 @ 위치에서 4번 들여쓰기합니다.

 

→ 네 가지 유형 중 필요한 것만 쓰인다. 아래 사진에서는 @param 과 @return만 쓰인 모습

7.2 The summary fragment (요약 조각)

각 Javadoc 블록은 간단한 요약 조각으로 시작됩니다 .
이 조각은 매우 중요합니다.
클래스 및 메서드 인덱스와 같은 특정 컨텍스트에 나타나는 텍스트의 유일한 부분입니다.

이것은 완전한 문장이 아니라 명사구 또는 동사 구인 단편입니다. 그것은 A {@code Foo} is a... 또는 This method returns...로 시작하지 않습니다. Save the record. 처럼 완전한 필수 문장을 형성 않습니다. 그러나 조각은 완전한 문장 인 것처럼 대문자로 표시되고 구두점으로 표시됩니다.

*주로 하는 실수: /** @return the customer ID 은 잘못 됨,  /** Returns the customer ID 이 옳음

 

→ thenThrow에 대한 JavaDoc의 첫 문장(빨간색 동그라미 표시)이 요약 조각이다.

7.1.3과 7.2에 대한 예시