'style guide'에 해당되는 글 7건

06. Javadoc :: 2021/11/17 17:50

/Programming Style Guide/java

개발자를 위한

Java Programming Style Guide (ref. Google style guide)

7. 문서화 (javadoc) 

7.1 서식(formatting)

1. 일반 서식 (General form)

Javadoc 블록의 기본적인 형식은 다음 예제에서 보는 것과 같습니다.

/**

 * Multiple lines of Javadoc text are written here,

 * wrapped normally...

 */

public int method(String p1) { ... }


또는 다음과 같은 하나의 라인으로 작성할 수 있습니다.

/** An especially short bit of Javadoc. */


기본적인 형식(basic form)은 항상 허용됩니다. Javadoc 블록 전체(주석 표시 포함)가 하나의 라인으로 작성할 수 있는 경우는 한 줄 형식으로 대체될 수 있습니다. @return과 같은 블록 태그가 없는 경우에만 해당됨을 유의하세요.

2. 단락(Paragraphs)

정렬된 선행 별표(aligned leading asterisk:’*’)만 포함하고 있는 하나의 빈 줄은 단락 사이와 블록 태그 그룹이 있을 경우 태그 그룹 앞에 나옵니다. 첫번째 단락을 제외한 각 단락은 첫번째 단어 바로 앞에 <p> 태그가 있고, 뒤에는 공백이 없습니다.

3. 블록 태그(Block tags)

코드에 사용하는 표준 “블록 태그(block tags)”는 @param, @return, @throws, @deprecated 순서로 사용되며, 이 4가지 유형은 설명이 비어 있으면 안 됩니다. 블록 태그가 한 줄에 맞지 않으면 @위치에서 4개 이상의 스페이스로 들여쓰기를 합니다.

7.2 요약 단편(the summary fragment)

각 Javadoc 블록은 간단한 요약 단편으로 시작합니다. 이 단편적인 요약은 매우 중요합니다.  클래스나 메서드 인덱스처럼 특별한 컨텍스트(context)에서 나타나는 텍스트의 유일한 부분입니다.

이 단편은 완전한 문장이 아니라 명사구나 동사 구절입니다. A {@code Foo}처럼 시작하지도 않고, “This method returns…”로 시작하지도 않고, “Save the rcord..”와 같은 완전한 명령형 문장의 형태로 시작하지도 않습니다. 하지만, 요약 단편에는 완전한 문장인 것처럼 대문자와 구두점이 있습니다.

Tip : 일반적으로 /** @return the customer ID */와 같이 Javadoc을 작성하는 실수를 하게 됩니다. 이것은 잘못된 것입니다. /** Returns the customer ID */처럼 변경해야 합니다.

7.3 Javadoc 사용처(where javadoc is used)

최소한, Javadoc은 모든 public class와 그 클래스에 있는 public, protected 멤버에 관해 존재하지만, 아래 언급된 몇 가지 예외가 있습니다.

아래 3번 Non-required Javadoc에 설명되어 있는 것처럼, 추가적인 Javadoc 컨텐츠가 있을 수 있습니다.

1. 예외(Exception) : 자체 서술적인 메서드 (self-explanatory methods)

getFoo와 같이 “단순하고 분명한(simple, obvious)” 메서드에 대해서 Javadoc을 작성하는 것은 선택 사항입니다. 이 경우처럼, “Returns the foo”라고 말하는 것 이외 아무것도 말할 가치가 없는 경우도 있습니다.

중요(important) : 일반적으로 독자가 알 필요가 있는 관련 정보를 생략하는 것을 정당화하기 위해 위에 언급된 예외를 적용하는 것은 적합하지 않습니다. 예를 들어, getCanonicalName의 메서드의 경우, 일반 독자가 “표준 이름(canonical name)”이라는 용어가 무엇을 의미하는지 모를 경우 해당 Javadoc 문서(단지 /** Returns the canonical name. */만을 말하고자 하는 이유일지라도)를 생략하면 안 됩니다.

2. 예외(Exception) : 재정의(override)

상위 유형(supertype) 메서드를 재정의하는 경우에는 항상 Javadoc이 존재하는 것은 아닙니다.

3. 불필요한 경우 (Non-required Javadoc)

다른 클래스와 멤버의 경우, 필요에 따라 Javadoc이 있습니다.

구현 주석(implementation comments)이 클래스나 멤버 전체의 목적이나 동작에 대해 정의하는데 사용되는 경우, 해당 주석은 Javadoc으로 작성될 수 있습니다. (/** 사용)

불필요한 경우의  Javadoc(non-required javadoc)은 위에서 정리한 단락(Paragraphs)이나 블록 태그(Block tags), 요약 단편(Summary fragments)의 형식을 따르도록 엄격하게 요구되지는 않지만, 될 수 있으면 정해진 형식을 따르기를 권고합니다.  

, ,
Trackback(21) : Comment(0)
[로그인][오픈아이디란?]
오픈아이디로만 댓글을 남길 수 있습니다
Name
Password
Homepage

Secret

05. Practice :: 2021/11/17 17:49

/Programming Style Guide/java

개발자를 위한

Java Programming Style Guide (ref. Google style guide)

6. 프로그래밍 실습 (Programming practices) 

6.1 @Override: always used

메서드(method)는 합법적일 때마다 @Override 어노테이션(annotation)으로 표시됩니다. 여기에는 슈퍼클래스(super class)의 메서드를 재정의(override)하는 클래스 메서드, 슈퍼인터페이스(super interface)의 메서드를 재지정(respecifying)하는 인터페이스 메서드를 포함합니다.

예외(Exception) : @Deprecared일 경우에는 @Override를 생략할 수 있습니다.

6.2 Caught exceptions: not ignored (예외가 발생했을 때, 무시하지 말 것)

아래 언급된 경우를 제외하고, 예외가 발생했을 때(caught exception) 아무런 응답을 하지 않는 것은 매우 드문 경우입니다. (일반적으로 응답(response)은 기록해야 합니다. 만약 기록이 불가능(“impossible”)하다고 여겨지는 경우에는 AssertionError를 다시 발생(rethrow)시킵니다.)

Catch 블록에서 아무 조치도 취하지 않는 것이 정말 적합할 경우, 정당화되는 이유가 코멘트로 설명되어 있습니다.

try {

  int i = Integer.parseInt(response);

  return handleNumericResponse(i);

} catch (NumberFormatException ok) {

  // it's not numeric; that's fine, just continue

}

return handleTextResponse(response);


예외(Exception) : 테스트에서 발견된 예외는 이름이 기대되는 예외일 경우, 주석없이 무시될 수 있습니다. 다음 코드는 예상되는 예외를 확인하기 위한 아주 일반적인 관용구이기 때문에 주석이 필요하지 않습니다.

try {

  emptyStack.pop();

  fail();

} catch (NoSuchElementException expected) {

}


6.3 정적 멤버(static members): 클래스를 사용하여 한정(qualified using class)

정적 클래스 멤버(static class member)에 대한 참조(reference)가 규정되어야 하는 경우, 클래스 유형(class type)의 참조나 표현식이 아니라 해당 클래스 이름으로 규정되어야 합니다.

Foo aFoo = ...;

Foo.aStaticMethod(); // good

aFoo.aStaticMethod(); // bad

somethingThatYieldsAFoo().aStaticMethod(); // very bad


6.4 종료자(finalizers) : 사용하지 않음(not used)

Object.finalize를 재정의(override)하는 것은 극히 드문 경우입니다. 사용하지 않습니다.

Tip : 사용하지 마십시오. 반드시 사용해야 할 것 같으면, 먼저 Effective Java 항목 7 “종료자 피하기(Avoid Finalizers)”를 매우 주의 깊에 읽고 이해한 다음에 사용하지 마세요.

, ,
Trackback(155) : Comment(0)
[로그인][오픈아이디란?]
오픈아이디로만 댓글을 남길 수 있습니다
Name
Password
Homepage

Secret

04. Naming :: 2021/11/17 17:48

/Programming Style Guide/java

개발자를 위한

Java Programming Style Guide (ref. Google style guide)

5. 네이밍(naming)


5.1 모든 식별자에 적용되는 공통 규칙(rules common to all identifiers)

식별자(identifier)는 ASCII 문자와 숫자만 사용하며, 아래에 언급된 소수의 경우에만 밑줄(underscore)를 사용합니다. 따라서, 각 유효한 식별자 이름은 정규식(regular expression) \w+ 와 일치합니다.

(구글 스타일에서는) 특수한 접두사나 접미사를 사용하지 않습니다. 예를 들어, name_, mName, s_name, kName과 같은 이름은 (구글) 스타일이 아닙니다.

5.2 식별자 유형별 규칙(rules by identifier type)

1. 패키지 명 (Package names)

패키지 명은 모두 소문자이며, 연속된 단어는 간단하게 서로 연결됩니다. (밑줄 없음) 예를 들어, com.example.deepSpace나 com.example.deep_space가 아니라 com.example.deepspace로 패키지명을 작성합니다.

2. 클래스 명 (Class names)

클래스 이름은 UpperCamelCase(단어가 시작되는 맨 앞 한글자를 대문자로 작성하는 유형)로 작성합니다. 클래스 이름은 일반적으로 명사나 명사구입니다. 예를 들어, Character 나 ImmutableList와 같습니다. 인터페이스(Interface) 이름은 명사나 명사구(예를 들면, List)일 수도 있지만, 때로 형용사나 형용사구가 될 수도 있습니다. (예 : Readable)

어노테이션 유형의 명명(naming annotation type)에 대해서는 특정 규칙이나 잘 정립된(well-established) 규정(convention)은 없습니다.

테스트 클래스(Test class)는 테스트 중인 클래스 이름으로 시작하여 Test로 끝나는 이름으로 명명합니다. 예 : HashTest 또는 HashIntegrationTest

3. 메서드 명 (Method names)

메서드 이름은 lowerCamelCase(맨 앞 한글자는 소문자로, 다음 단어의 맨 앞 한글자는 대문자로 작성하는 유형)로 작성합니다. 메서드 이름은 일반적으로 동시 또는 동사구로 작성합니다. 예를 들면 다음과 같습니다. 

Ex) sendMessage 또는 stop

밑줄은 lowerCamelCase로 작성된 각 컴포넌트와 이름을 논리적으로 구분하기 위해 JUnit 테스트 메서드에 나타날 수 있습니다. 한가지 일반적인 패턴은 <methodUnderTest>_<state>의 형태입니다. (예: pop_emptyStack). 테스트 메서드의 이름을 지정하는 단 한가지의 완벽한 방법은 없습니다.

4. 상수 명 (Constant names)

상수 명은 CONSTANT_CASE와 같은 유형을 사용합니다. 상수 명은 모두 대문자이며, 각 단어는 하나의 밑줄로 다음 단어와 구분됩니다. 하지만, 정확하게 상수가 무엇일까요?

상수는 내용이 변경되지 않고(immutable), 메서드에 부작용(side effect)이 전혀 없는 static final field 입니다. 여기에는 기본형(primitives), 스트링형(Strings), 불변 유형(immutable type), 불변 유형의 불변 컬렉션(immutable collection)이 포함됩니다. 만약 인스턴스의 관찰 가능한 상태가 변경될 수 있다면, 그것은 상수가 아닙니다. 객체를 변경하지 않으려는 의도만으로는 충분하지 않습니다.

예를 들면 다음과 같습니다.

// 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 }


// Not constants

static String nonFinal = "non-final";

final String nonStatic = "non-static";

static final Set<String> mutableCollection = new HashSet<String>();

static final ImmutableSet<SomeMutableType> mutableElements = ImmutableSet.of(mutable);

static final ImmutableMap<String, SomeMutableType> mutableValues =

    ImmutableMap.of("Ed", mutableInstance, "Ann", mutableInstance2);

static final Logger logger = Logger.getLogger(MyClass.getName());

static final String[] nonEmptyArray = {"these", "can", "change"};


이러한 이름은 일반적으로 명사나 명사구입니다.

5. 비상수 필드 명 (Non-constant field names)

상수가 아닌 필드 명(non-constant field name)은 (static이든 아니든) lowerCamelCase로 작성됩니다.

이러한 이름은 일반적으로 명사 또는 명사구로 작성됩니다.

예를 들면 다음과 같습니다.

Ex) computedValues 또는 index

6. 파라미터 명 (Parameter names)

파라미터(매개변수 : parameter) 명은 lowerCamelCase로 작성됩니다.

Public 메서드에서 단일 문자 파라미터 이름은 피해야 합니다.

(다른 사람이 변수 명을 이해할 수 없습니다.)

7. 지역 변수 명 (Local variable names)

지역 변수 명은 lowerCamelCase로 작성합니다. final이나 immutable의 경우에도, 지역 변수는 상수로 간주하지 않으며 상수 스타일로 코드를 작성하면 안 됩니다.

8. 유형 변수 명 (Type variable names)

각 유형 변수 명은 다음 2가지 스타일 중 하나로 작성합니다.

 - 단일 대문자, 선택적으로 뒤에 단일 숫자 추가 (ex. E, T, X, T2)

 - 클래스에 사용되는 형태의 이름 뒤에 대문자 T (ex. RequestT, FooBarT)

5.3 카멜 케이스(camel case : defined)

“IPv6”이나 “iOS”와 같이 두문자어나 특이한 구조가 있는 경우처럼 영어 구문을 Camel Case(영어 대소문자로 변환)로 변환하는 합리적인 방법이 한가지 이상 있습니다. 예측 가능성을 개선하기 위해서 Google Style 표준에서는 다음과 같은 (거의) 결정적인 스키마를 지정합니다.


산문형 이름으로 시작 : 

1. 어구를 ASCII로 변환하고 Apostrophe(‘)를 제거하세요. 예를 들어, “Müller's algorithm”는 “Muellers algorithm”으로 변환됩니다.

2. 이 결과를 공백과 나머지 구두점(punctuation)으로 (일반적으로 hypen: ‘-‘)으로 분할하여 나눕니다.

    • 권장(Recommended) : 이미 전통적인 Camel Case를 일반적으로 사용하고 있다면, 구성요소로 분할합니다. (예 : AdWord는 ad word로 분할됨) 하지만, “iOS”와 같은 경우는 Camel Case가 아니기 때문에 어떤 규칙에도 위배됩니다. 따라서 이 권장사항은 적용되지 않습니다.

3. 모든 항목(약어 포함)을 소문자로 만든 다음, 첫번째 문자만 대문자로 합니다.

    • … 각 단어를 Upper Camel Case로 사용하거나, (각 단어의 첫글자를 대문자로)
    • … 각 단어의 첫번째 글자를 제외하고,  Lower Camel Case로 사용합니다. (첫 단어의 첫글자 소문자, 다른 단어의 첫글자는 대문자로)

4. 끝으로, 모든 단어를 단일 식별자로 결합합니다.

원래 단어의 대소문자는 거의 대부분 무시되는 것에 유의하세요.

예:

Prose form

Correct

Incorrect

"XML HTTP request"

XmlHttpRequest

XMLHTTPRequest

"new customer ID"

newCustomerId

newCustomerID

"inner stopwatch"

innerStopwatch

innerStopWatch

"supports IPv6 on iOS?"

supportsIpv6OnIos

supportsIPv6OnIOS

"YouTube importer"

YouTubeImporter

YoutubeImporter*


YoutubeImporter* : 수용 가능하지만, 권장하지 않습니다.


Note : 일부단어는 영어에서 모호하게 ‘-‘으로 연결됩니다. : 예를 들어, “nonempty”와 “non-empty”는 모두 정확하기 때문에 checkNonempty, checkNonEmpty도 모두 정확한 표현입니다.

, ,
Trackback(165) : Comment(0)
[로그인][오픈아이디란?]
오픈아이디로만 댓글을 남길 수 있습니다
Name
Password
Homepage

Secret

03. formatting - 02 :: 2021/11/17 16:46

/Programming Style Guide/java

개발자를 위한

Java Programming Style Guide (ref. Google style guide)

4.6 공백(whitespace)

  1. 세로 공백(Vertical Whitespace)

  다음과 같은 경우에 하나의 빈줄은 항상 나타납니다.

  1) 클래스의 연속된 멤버(consecutive member) 또는 초기자(initializer) 사이 : 필드(field), 생성자(constructors), 메서드(method), 중첩 클래스(nested classes), 정적 초기자(static initializers), 인스턴스 초기자(instance initializers)

    • 예외(exception) : (다른 코드가 없는) 두 개의 연속된 필드 사이에서 빈줄 사용은 선택사항입니다. 필드의 논리적 그룹을 만들기 위해 필요에 따라 빈줄을 사용할 수 있습니다.
    • 예외(exception) : 열거형 상수(enum constants) 사이의 빈 줄은 다른 섹션에서 다룹니다.

  2) 이 문서의 다른 섹션인 소스 파일 구조(Source File Construction)나 임포트 구문(Import Statements)에서 정의된 대로 세로 공백을 사용할 수 있습니다.

  예를 들어, 코드를 논리적인 하위 섹션으로 구조화하기 위한 구문 사이에서 처럼, 코드의 가독성을 개선시키기 위해서라면 어디든지 빈줄 하나를 사용할 수 있습니다. 첫번째 멤버(first member)나 초기자(initializer) 전에 빈줄을 두거나, 클래스의 마지막 멤버(last member)나 초기자(initializer) 다음에 빈줄을 두는 것은 권장하지 않고, 비권장하지도 않습니다.

  여러 개의 연속되는 공백 라인(blank line)은 허용되지만, 결코 필수(또는 권장)는 아닙니다.

  1. 가로 공백(Horizontal whitespace)

  프로그래밍 언어(language)나 다른 스타일 규칙(style rules)에서 요구하는 것을 넘어, 리터럴(literals)과 주석(comment) 및 Javadoc을 제외하고 단일 ASCII 스페이스도 다음 위치에서만 사용해야 합니다.

  1) if, for, catch와 같은 예약어를 해당 줄에서 뒤에 오는 여는 괄호(()와 분리하기 위해 스페이스 사용 (ex. if (… )

  2) else나 catch와 같은 예약어를 해당 줄에서 앞에 오는 닫는 중괄호(})와 분리하기 위해 스페이스 사용 (ex. …) else )

  3) 여는 중괄호({) 앞에 스페이스(띄어쓰기)를 사용하지 않는 2가지 예외가 있습니다.

    • @SoneAnnotation({a, b}) (‘({‘ 사이에 스페이스 사용되지 않음)
    • String[][] x = {{“foo”}}; (‘{{‘ 사이에 스페이스 필요 없음)

  4) 2항이나 3항 연산자 양쪽에 있습니다. 다음과 같은 “연산자와 유사한(operator-like)” 기호에도 적용됩니다.

    • 결합형으로 묶여 있는 엠퍼센트(&) : <T extends Foo & Bar>
    • 여러 개의 예외를 처리하는 catch 블록의 파이프 : catch (FooException | BarException e)
    • 향상된 for 구문(“foreach”) 내의 콜론(:)
    • 람다 식의 화살표: (String str) -> str.length()

그러나, 다음과 같은 경우에는 스페이스를 사용하지 않습니다. 

    • Object::toString과 같이 작성된 메서드(method) 참조에 사용되는 2개의 콜론(::)
    • object.toString()과 같이 작성된 dot 구분자(. seperator)

  5) , : ; 뒤나 캐스트(cast)의 닫는 괄호( ‘)’ ) 뒤에 스페이스 사용

  6) 라인의 끝에서 코멘트(comment)의 시작인 더블 슬래쉬(//)의 앞뒤 양쪽

  7) 유형과 변수 선언 사이 : List<String> list

  8) (Optional) 배열 초기자(array initializer)의 양쪽 중괄호 사이

    • new int[] {5, 6} 와 new int[] { 5, 6 } 모두 유효함

 9) 어노케이션 유형과 대괄호([]) 혹은 … 사이

이 규칙은 라인의 시작이 끝부분에서 스페이스를 추가하는 부분에 대한 요구사항이나 금지사항이 아닙니다. 단지 라인의 내부 공간에서의 규칙 만을 다룹니다.

  1. 가로 정렬(Horizontal alignment) : 필요 없음(never required)

Terminology Note(용어집) : 수평 정렬은 특정 토큰이 이전 라인의 다른 토큰 바로 아래에 나타나도록 코드에 다양한 숫자의 공백을 추가하는 방법입니다.

이 방법은 허용되지만, 필수로 요구하지는 않습니다. 이미 사용된 부분에서 수평 정렬을 유지할 필요도 없습니다.

정렬이 없는 경우와 정렬을 사용하는 경우에 대한 예제는 다음과 같습니다.

private int x; // this is fine

private Color color; // this too


private int   x;      // permitted, but future edits

private Color color;  // may leave it unaligned


Tip : 정렬은 가독성에 도움이 될 수 있지만, 향후 유지관리(maintenance)에 문제가 됩니다. 한줄만 수정해야 하는 미래의 변화를 고려해 보면, 이 변화로 인해 이전에 만족스러웠던 서식이 엉망이 될 수 있습니다. 이것은 코더에게 더 자주 근처 라인의 공백을 조정하도록 프롬프트를 표시하여 연쇄적인 재형식화(reformatting)를 유발할 수 있습니다. 그 한 라인의 변경은 “폭발 반경(blast radius)”를 가지게 됩니다. 최악의 경우에 무의미한 작업을 초래할 수 있지만, 기껏해야 버전 정보를 손상시키고 검토자의 속도를 늦추며 병합 충돌을 일으키는 정도입니다.

4.7 그룹화 괄호(Grouping parentheses) : 권장(recommended)

선택적인 그룹화 괄호는 작성자(author)와 검토자(reviewer) 사이에 그것들이 없어도 코드를 잘못 해석하지 않고 코드를 더 읽기 쉽게 만들 수 있다는 점에 동의하는 경우에만 생략 가능합니다. 모든 리더(reader)가 전체 Java 연산자 우선순위 테이블을 기억하고 있다고 가정하는 것은 전혀 합리적이지 않습니다.

4.8 특별한 구조(specific constructs)

1. Enum Classes

열거형 상수(enum constant) 다음에 오는 각 쉼표 뒤에 줄 바꿈(line break)은 선택 사항입니다. 추가 빈줄(보통 한 줄)도 허용됩니다. 다음은 한가지 가능한 예제입니다.

private enum Answer {

  YES {

    @Override public String toString() {

      return "yes";

    }

  },


  NO,

  MAYBE

}


메서드(method)가 없고, 상수에 대한 문서가 없는 열거형 클래스(enum class)는 배열 초기자(array initializer)인 것처럼 선택적으로 형식화 될 수 있습니다.

private enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS }


열거형 클래스(enum class)는 클래스이기 때문에 클래스에 적용되는 모든 형식 지정 규칙이 적용됩니다.

2. 변수 선언(Variable declarations)

 1) 선언 당 하나의 변수 (One variable per declaration)

모든 변수 선언(필드 또는 로컬)은 하나의 변수만 선언합니다. int a, b;와 같은 선언은 사용하지 않아야 합니다.

예외) for 루프문 헤더에는 여러 변수 선언이 허용됩니다.

 2) 필요할 때 선언(Declared when needed)

지역 변수(local variable)를 포함하고 있는 블록이나 블록과 유사한 구조의 시작 부분에 습관적으로 선언하지 않아야 합니다. 대신에, 지역 변수는 범위를 최소화하기 위해 처음 사용되는 지점에(사용 이유와 함께) 가까운 곳에 선언합니다. 지역변수를 선언한 후, 일반적으로 초기자(initializer)가 있거나 선언 바로 다음에 지역 변수를 초기화합니다. 

3. 배열(Arrays)

 1) 배열 초기자(Array initializer) : “블록과 유사한” 형태가 될 수 있음

배열 초기자는 “블록과 유사한 구조”처럼 형식화 될 수 있습니다. 예를 들어 아래와 같은 형태는(완전한 목록은 아니지만 : not exhaustive list) 모두 유효합니다.

new int[] {

 0, 1, 2, 3

}

new int[] {

 0,

 1,

 2,

 3,

}

new int[] {

 0, 1,

 2, 3

}

new int[]

 {0, 1, 2, 3}   

 2) C-Style로 배열을 선언하면 안 됩니다.

대괄호는 변수의 일부가 아니라, 유형의 일부가 되어야 합니다.

String args[]가 아니라 String[] args의 형태로 선언되어야 합니다.

4. 스위치 구문(switch statements)

Terminology Note(용어집) : 스위치 블록의 괄호 안에서 하나 이상의 구문 그룹(statement group)이 있을 수 있습니다. 각 구문 그룹은 하나 이상의 구문이 있는 하나 이상의 스위치 레이블(switch labels)로 이루어져 있습니다.(마지막 구문 그룹에는 0개 이상의 구문이 있습니다.)

 1) 들여쓰기 (Indentation)

다른 블록과 마찬가지로, 스위치 블록의 내용은 +2만큼(+2 스페이스) 들여쓰기 됩니다.

스위치 레이블(switch label) 뒤에는 줄 바꿈이 있고, 들여쓰기 수준은 블록을 여는 것처럼 정확히 +2 증가합니다. 다음 스위치 레이블은 블록이 닫힌 것처럼 이전 들여쓰기 수준으로 돌아갑니다.

 2) 실현되지 못한 부분 : 주석처리(Fall-through : commented)

스위치 블록 내에서 각 구문 그룹(statement group)은 갑자기 종료되거나(break, continue, return, 또는 thrown exception 구문과 함께), 다음 구문 그룹이 실행됨을 나타내거나, 다음 구문 그룹으로 계속됨을 나타내는 주석으로 표시될 수 있습니다. 실현되지 못한 부분(fall-through)에 대한 아이디어를 전달하는 주석으로 충분합니다.(일반적으로 //로 실현되지 못한 부분을 표시) 스위치 블록의 마지막 구문 그룹에는 이 특별한 주석이 필요하지 않습니다.

예를 들면,

switch (input) {

  case 1:

  case 2:

    prepareOneOrTwo();

    // fall through

  case 3:

    handleOneTwoOrThree();

    break;

  default:

    handleLargeNumber(input);

}


case 1 뒤에는 주석이 없음을 유의하세요. 구문 그룹의 끝에만 주석이 있습니다. 

3) default 케이스는 기본임 (The default case is present)

각 스위치 구문에는 코드가 없는 경우에도 default 구문 그룹이 포함되어 있습니다.

예외(exception) : 열거형 유형(enum type)에 대한 스위치 구문은 해당 유형의 모든 가능한 값을 가지는 명시적 사례를 포함하는 경우 default 구문을 생략할 수 있습니다. 이 때문에 IDE나 다른 정적 분석 도구에서 누락된 사례가 있는 경우 경고를 나타낼 수 있습니다.

5. 어노테이션 (Annotations)

클래스(class), 메서드(method)나 생성자(constructor)에 적용되는 어노테이션은 문서 블록(documentation block) 바로 다음에 나타납니다. 그리고 각 어노테이션은 그 자체 행에 나열됩니다.(즉, 라인 당 하나의 어노테이션). 이와 같은 줄바꿈(line break)은 라인 변경(line-wrapping)(섹션   line-wrapping)을 구성하지 않기 때문에 들여쓰기 수준이 증가하지 않습니다.

예를 들면,

@Override

@Nullable

public String getNameIfPresent() { ... }


예외(Exception) : 매개변수가 없는 단일 어노테이션은 서명(signature)의 첫번째 라인과 함께 대신 나타날 수 있습니다. 예를 들면 다음과 같습니다.

@Override public int hashCode() { ... }


필드(field)에 적용된 어노테이션은 문서 블록(documentation block)의 바로 다음에 나타납니다. 그러나 이런 경우, 여러 개의 어노테이션(매개변수화 가능한)이 동일 라인에 나열될 수 있습니다. 예를 들면 다음과 같습니다.

@Partial @Mock DataLoader loader;


6. 주석 (Comments)

이 섹션에서는 구현 주석(implementation comments : 소스코드에 대한 주석)만 다룹니다. Javadoc에 대해서는 별도의 Javadoc 섹션에서 다룹니다.

모든 줄바꿈에는 임의의 공백(whitespace)이 있고, 그 다음에 구현 주석이 올 수 있습니다. 그러한 주석은 비어 있는 라인(line non-blank)이 아닌 것으로 취급합니다(render).

 1) 블록 주석 스타일 (block comment style)

블록 주석은 주변 코드와 같은 수준으로 들여쓰기 합니다. 블록 주석은 /* …. */ 형태나 // …. 형태로 나타납니다. 여러 라인의 /* … */ 주석에서 후속 라인은 이전 라인의 *와 정렬된 *로 시작해야 합니다. 

/*

 * This is

 * okay.

 */


// And so

// is this.


/* Or you can

 * even do this. */


블록별표나 다른 문자와 함께 그려진 박스(box)는 주석에 포함되지 않습니다.

 Tip : 여러 라인의 주석을 작성할 때, 자동 코드 포맷터(automatic code formatters)가 필요할 때 라인을 다시 감싸도록(re-wrap)(단락 스타일 : paragraph-style) 하기 위해서 /* … */ 형태를 사용하세요. 대부분의 포맷터(formatters)는 // … 형태의 주석 블록에서 라인을 다시 감싸지 않습니다(don’t re-wrap).

7. 수정자(Modifiers)

클래스(class)와 멤버(member) 수정자가 있는 경우, Java 언어 표준(Java language specification)에서 권장하는 순서대로 나타납니다.

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


8. 숫자형 문자열(Numeric Literals)

long 형 값을 가지는 정수 문자열(integer literals)은 대문자 L 접미사를 사용하고, 결코 소문자를 사용하지 않는다. (숫자(digit)1과의 혼동을 피하기 위해서) 예를 들면, 300000000l 이 아니라 300000000L을 사용한다. 

,
Trackback(167) : Comment(0)
[로그인][오픈아이디란?]
오픈아이디로만 댓글을 남길 수 있습니다
Name
Password
Homepage

Secret

03. formatting - 01 :: 2021/11/17 16:45

/Programming Style Guide/java

개발자를 위한

Java Programming Style Guide (ref. Google style guide)

4. 서식(Formatting)

Terminology Note(용어 참고) : 블록과 유사한 구성(block-like construct)은 클래스(class), 메서드(method)나 생성자(constructor)의 본문(body)를 나타냅니다. 단, 모든 배열 초기자(array initializer)는 선택적으로 블록과 유사한 구성으로 작성될 수 있습니다.

4.1 중괄호(braces)

  1. 중괄호를 선택적으로 사용하는 경우

중괄호는 본문이 비어 있거나, 단일 구문만 포함하고 있는 경우에도, if, else, for, do, while 문과 함께 사용됩니다.

  1. 비어 있지 않은 블록 (K&R Style)

중괄호는 비어 있지 않은 블록이나 블록과 유사한 구성에K&R Style(Kernighan and Ritchie Style) (“이집트 대괄호”)를 따릅니다.

  • 여는 중괄호(opening brace) 전에는 줄바꾸지 않습니다(No line break).
  • 여는 중괄호 다음에는 줄바꿈합니다(Line break).
  • 닫는 중괄호(closing brace) 전에 줄바꿈합니다.
  • 만약 구문이 종료되거나, 메서드나 생성자, 명명된 클래스의 본문이 종료되는 경우, 닫는 중괄호 다음에 줄바꿈합니다. 예를 들어, else나 쉼표(comma)가 뒤에 오는 경우에는 닫는 중괄호 다음에 줄 바꿈을 하지 않습니다.

<실제 사용 예>

return () -> {

  while (condition()) {

    method();

  }

};


return new MyClass() {

  @Override public void method() {

    if (condition()) {

      try {

        something();

      } catch (ProblemException e) {

        recover();

      }

    } else if (otherCondition()) {

      somethingElse();

    } else {

      lastThing();

    }

  }

};


다만, 열거형 클래스(Enum Class)에는 몇 가지 예외가 있습니다.

  1. 빈 블록(Empty blocks) : 잘 활용하면 간결해질 수 있음

빈 블록이나 블록과 유사한 구성을 K&R Style(Kernighan and Ritchie Style)로 작성할 수 있습니다. 다중 블록 구문(여러 블록을 직접적으로 포함하는 if/else, try/catch/finally 구문처럼)의 일부가 아닌 한, 중괄호({}) 사이에 문자나 줄바꿈 없이 중괄호 오픈 후, 바로 닫을 수 있습니다.

<실제 사용 예>

  // This is acceptable

  void doNothing() {}


  // This is equally acceptable

  void doNothingElse() {

  }


// This is not acceptable: No concise empty blocks in a multi-block statement

  try {

    doSomething();

  } catch (Exception e) {}


4.2 블록 들여쓰기(block indentation) : +2 스페이스(spaces)