java 컨벤션 가이드 - google

1. 코딩 컨벤션 종류

• goole java 컨벤션 가이드
• 오라클 java 컨벤션 가이드
• 네이버 java 컨벤션 가이드

 

• 참고 - sql 컨벤션
• 오라클 SQL & PL/SQL Optimization

 

1.1 IntelliJ 적용 하기

• 기본적으로 IntelliJ용으로 셋팅이 되어있다.
  • 네이버 컨벤션 포맷
  • 구글 켄벤션 포맷 

 

1. 위 링크에서 IntelliJ용 xml 포맷터 다운로드
2. IntelliJ IDEA - Preferences > Editor > Code Style 
3. Scheme 우측 톱니바퀴 > Import Scheme > IntelliJ IDEA code style XML 클릭
4. 다운로드 받은 XML 포맷터를 찾아서 적용

 

2. 소스 파일 기본 사항

• 소스파일
  • .java
• 클래스파일
  • .class
  • 바이너리 파일
• 컴파일러
  • javac
• 동작 방식
  1. 소스코드(MyProgram.java) 작성
  2. 컴파일러(Compiler)는 자바 소스코드를 이용하여 클래스 파일(MyProgram.class)을 생성
  3. JVM은 클래스 파일의 바이너리 코드를 해석하여 프로그램을 수행
  4. MyProgram 수행 결과가 컴퓨터에 반영

 

2.1. 파일 이름

• 하나의 파일에 하나의 class만 존재
• 파일 명과 class명은 동일
• .java 확장자여야한다.
• 여러 단어일 경우 UpperCamelCase

 

2.2. 파일 인코딩: UTF-8

• 소스 파일은 UTF-8로 인코딩

 

2.3. 특수 문자

    2.3.1. 공백문자

• 개행 문자(줄바꿈 문자)를 제외하고, ASCII 코드 공백문자(0x20)는 소스 파일에서 유일한 공백문자
  = enter 빼고 space만 유일한 공백 문자로 쓸꺼야. 다른 공백문자 쓰지마
  
  1. String이나 문자 리터럴에서 공백문자는 escape 된다.
     = string이나 char 내부에 엔터라던지 탭 같은 공백 문자 써야할 때는 escape 사용해. space는 그냥 space되니깐 굳이..?
  2. 들여쓰기 할 대 tab 쓰지말고 space 사용해

    2.3.2. escape 되는 특수문자

• 우선 순위 :   \b   \t   \n    \f    \r   \"   \'   \\       >     octal방식( \012 )이나 유니코드(\u000a )

    2.3.3. ASCII 코드 외의 문자

ASCII (American Standard Code for Information Interchange)는 정보 교환을 위한 미국 표준 코드입니다. 

이것은 7비트 이진 코드 체계로, 문자와 제어 문자를 숫자로 표현하는 데 사용됩니다. 

ASCII 코드는 1960년대에 개발되었으며 현재까지도 텍스트 데이터의 인코딩과 통신에서 널리 사용됩니다.

ASCII 코드는 0부터 127까지의 값을 사용하며, 다음과 같은 문자와 제어 문자를 포함합니다:

0부터 31까지의 제어 문자 (예: 줄 바꿈, 탭, 캐리지 리턴)
32부터 126까지의 인쇄 가능한 문자 (예: 알파벳, 숫자, 기호)
127: 삭제 문자 (DEL, Delete)
ASCII 코드는 다양한 컴퓨터 및 통신 시스템에서 텍스트 데이터를 표현하는 데 사용되며, 이를 통해 컴퓨터 간의 상호 운용성이 확보됩니다. 예를 들어, "A"는 ASCII 코드에서 65로 표현되고, "a"는 97로 표현됩니다.

ASCII 코드는 더 나은 국제화 및 다양한 문자 집합의 지원을 위해 확장된 버전인 UTF-8, UTF-16, UTF-32와 같은 유니코드 인코딩으로 대체되는 추세이지만, ASCII 코드는 여전히 중요한 역할을 하고 있으며, 많은 컴퓨터 시스템 및 프로그래밍 언어에서 기본적인 텍스트 표현에 사용됩니다.

• 아스키코드가 아닌 문자는 Unicode character ( ∞ )나, Unicode escape  ( \u221e)가 활용된다.
• 가장 읽기 좋은 방식으로 선택하는 것이 좋다.
• 예시

String unitAbbrev = "μs";  - Best

String unitAbbrev = "\u03bcs"; // "μs" - 허락되지만 이렇게 할 이유가 없음

String unitAbbrev = "\u03bcs"; // Greek letter mu, "s" - 허락되지만 이상해보이고, 오해를 살 여지가 있음

String unitAbbrev = "\u03bcs"; - 최악, 이게 뭔지 알 도리가 없음

 

 

3. 소스 파일 구조

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

• License 와 저작권 정보가 존재한다면 최상단에 적어준다.
• 패키지, 코드 파일, 프로젝트 시작 부분에 기록하라는 의미

 

3.2. 패키지 명세서

• 패키지 문은 개행하지 않으며, 열 제한이 적용되지 않는다.

 

3.3. Import 문

    3.3.1. No wildcard(*) import

• 와일드카드 방식으로 가져오지 않는다. ex) import java.util.*;
• 와일드카드로 가져온 두개의 import 된 패키지에 동일한 이름의 method 가 선언되어 있는 경우 이를 명시해주지 않으면 컴파일 오류를 일으킨다. 

    3.3.2. No line-wrapping

• import 문 역시 개행하지 않는다. 열 제한 역시 적용되지 않는다.

    3.3.3 Ordering and spacing

• 순서와 위치
• Import 문들은 아래의 순서를 따른다.
  1. 모든 static import가 포함된 하나의 블록
  2. 모든 non-static import가 포함된 하나의 블록

    3.3.4 No static import for classes

• 중첩 클래스 중 제일 내부의 클래스의 메서드를 사용할 때 static import 를 사용하지 않는다. 
• 예시

public class OuterClass {
    public static class InnerClass {
        public static void innerMethod() {
            System.out.println("Inner method");
        }
    }
}

// static import를 사용 하지 않는다.
import some.package.OuterClass.InnerClass;

public class AnotherClass {
    public static void main(String[] args) {
        InnerClass.innerMethod(); // InnerClass를 사용하여 innerMethod 호출
    }
}

 

3.4. 클래스 선언

• 정확히 하나의 최상위 클래스 선언
• 클래스 멤버와 생성자에는 정해진 순서는 없다. 하지만 순서에 논리가 존재해야한다.
• 다만, Overload된 동일한 이름을 지니는 멤버는 분리되어있으면 안된다.

 

4. 포맷

4.1. use of optional braces

    4.1.1. Use of optional braces

• if, else, for, do, while 문과 함께 사용되는 중괄호는 바디가 비어있거나 단 하나의 statement 만 포함하는 경우에도 생략되면 안된다.
• 람다 표현식과 같은 중괄호는 선택 사항

    4.1.2. Nonempty blocks: K & R style

1. 하단에 자세하게 설명된 내용 외의 중괄호를 열기 전에는 개행하지 않는다.
2. 중괄호를 열고 난 후에는 개행한다.
3. 중괄호를 닫기 전에는 개행한다.
4. 중괄호를 닫은 후에 구문이 종료되거나, 메소드의 바디, 생성자, 구체화 클리스 등이 종결되는 상황에서만 개행한다. if 이후에 else 문이나오는 경우나 콤마(,)가 나오는 경우에는 중괄호를 닫은 후에 개행하지 않는다.

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();
    }
    {
      int x = foo();
      frob(x);
    }
  }
};

    4.1.3. Empty blocks

• 빈 블록에서 중괄호는 개행은 선택사항이다. 개행을 해도 되고 하지 않아도 된다. 다만,  try~catch 문이나 if~else 문 같은 멀티블록 상황에서는 개행을 해야만 한다.

  // 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. 블록 들여쓰기

• 매 새로운 블록 혹은 블록 형태의 구조가 열릴 때마다, 두 개의 공백이 추가된다. 블록이 끝나면, 들여쓰기 level 은 이 전의 들여쓰기 level로 변한다. 즉 다시 공백문자 2개가 제거된다. 이 들여쓰기 level 은 코드와 주석에 모두 적용된다. 
• 4개 쓰는 곳도 있으니깐 상황에 맞춰 사용

 

4.3. 한 줄에 하나의 문장

• 하나의 줄에는 하나의 구문만 존재한다.

 

4.4. 열 제한: 100

• 자바의 코드는 한 줄에 100개의 문자 제한을 가진다. 이 "문자" 의 의미는 유니코드 포인트를 의미하며, 하단에 정리된 예외를 제외하는 모든 줄은 줄 바꿈 규칙을 준수해야 한다. 
• 예외
  1. Javadoc의 URL 이나 긴 JSNI 메소드 참조 처럼 열 제한을 지키는 것이 불가능한 경우
  2. Package 나 improt 문
  3. 주석 내의 쉘에 붙여넣을 수 있는 내용
  4. 매우 긴 식별자의 경우 거의 호출되지 않지만, 열 제한을 초과할 수 있다. 이 경우 이를 둘러싼 주변 코드를 위한  wrapping 은 google-java-format 을 참조하자.

 

4.5. 줄 바꿈

• 한 줄에 포함될 수 있는 규칙을 가진 코드를 여러 줄로 나누는 것을 줄바꿈이라고 표현한다.
• 모든 경우에서 어떻게 줄바꿈을 해야하는지를 설명하는 포괄적이고 결정적인 공식은 없으며 다양한 방식이 있다.
• 통상 줄바꿈을 하는 이유는 열 제한을 피하기 위해서, 혹은 열 제한은 만족하지만 코드 작성자의 재량(가독성을 위해)에 의해서 줄바꿈을 할 수 있다. 
• Tip : 메소드 호출 혹은 지역변수를 사용하는 것은 줄바꿈을 대신해서 이 문제를 해결할 수 있다.

    4.5.1. 줄바꿈 위치 (naver 컨벤션 규칙 예시 추가)

• Google style 의 다른 언어에서는 동일하게 사용되지 않는다.
• 더 높은 레벨의 구문에서 끊어주는 것을 원칙으로 한다. 
  1. non-assignment operator (대입 연산자가 아닌 이외의 연산자) 에서 줄이 끊어질 때, symbols 앞에서 줄을 끊어 줄바꿈을 해준다. 이는 연산자와 같은 symbols 들에게대 동일하게 적용한다.
     
     • 점 구분기호(.)
     • 메소드 참조(::)
     • 타입 바운드에서 앤드기호(&)
     • catch 블록에서 pipe (|)
  2. 대입 연산자에서 줄이 끊어지면 일반적으로 기호 뒤에 줄바꿈이 오지만 어느 쪽이든 상관없다. 이는 향상된 for 문의 콜론에도 적용된다.
  3. 메서도 또는 생성자 이름 뒤에 오는 여는 괄호는 붙여준다.
  4. 쉼표는 앞에 오는 토큰에 붙여준다.
  5. 람다의 본문이 중괄호가 없는 단일 표현식으로 구성된 경우 화살표의 바로 뒤에서 줄이 끊어지는 경우를 제외하고는 람다의 화살표 옆에서 줄바꿈을 하지 않는다.
• 줄 바꿈의 가장 최우선적인 목표는 코드의 가독성이다. 줄이 몇개 없는 코드의 경우 줄바꿈이 크게 필요하지 않다.
  
  
• (naver 예시) 가독성을 위해 줄을 바꾸는 위치는 다음 중의 하나로 한다.
  
  • extends 선언 후    implements 선언 후    throws 선언 후    시작 소괄호(() 선언 후    콤마(,) 후
  • . 전    연산자 전 (연산자 :  +, -, *, /, %    ==, !=, >=, >,⇐, <, &&, ||    &, |, ^, >>>, >>, <<, ?    instanceof    )

public boolen isAbnormalAccess (
    User user, AccessLog log) {

    String message = user.getId() + "|" | log.getPrefix()
        + "|" + SUFFIX;
}

    4.5.2. Indent continuation lines at least +4 spaces

• 줄 바꿈 이후에는 기존의 라인보다 4개 이상의 들여쓰기를 해준다.
• 연속행이 여러개인 경우 공백을 4개 이상으로 들여쓸 수 있다.
• 일반적으로 병렬요소(스트림)인 두 개의 연속행에 대해서는 동일한 수준의 들어쓰기를 사용한다.

 

4.6. 공백

    4.6.1 Vertical Whitespace

• 클래스의 연속 멤버 혹은 생성자 사이에, 문서의 다른 섹션에는 하나의 빈 줄이 항상 들어간다.
• 예외
  1. 두 개의 연속 field 에 대한 빈 줄은 선택사항이다.
  2. enum 상수에 대한 빈 줄은 section 4.8.1 에서 설명한다.

4.6.2 Horizontal whitespace

• 수평 공백
  
  1. if,for,catch  등의 모든 예약어 의 여는 괄호 사이에 공백
  2. else, catch 등의 예약어의 닫는 중괄호 앞의 공백
  3. 모든 여는 중괄호 앞에
  4. 이항, 3항 연산자, 연산자 앞뒤 + 연산자 같은 symbols 들도 마찬가지
• 예외 
  • @SomeAnnotation({a, b}) (no space is used)
  • String[][] x = {{"foo"}}; (no space is required between {{, by item 9 below)
• 수평 정렬은 코드의 가독성을 좋게 만들기 위해서 몇개의 공백을 추가적으로 넣는 것을 의미한다.
• 일반적으로 허용되기는 하지만 구글 스타일에서는 절대 사용되지 않는다.
• 이는 향후 유지관리에 문제가 되기 때문이다.

 

4.7. 그룹화 괄호: 권장

• 독자 전체가 JAVA 연산자의 우선순위 관계를 알고 있다고 가정하는 것은 합리적이지 않다.
• 그래서 선택적으로 그룹화하기 위해 사용되는 괄호는 코드의 작성자나 리뷰어가 코드를 잘못 해석하거나 코드를 읽기 어렵게 만드는 경우를 제외하고 허용된다. 

 

4.8. 특정 구성

    4.8.1 Enum classes

• 열거형 상수 다음에 오는 각 쉼표 뒤의 줄바꿈은 선택사항이다.
• 또한 추가적인 한 줄의 공백도 허용된다.
• 또한 메소드나 요소에 대한 문서가 없는 열거형 클래스의 경우 배열 이니셜라이저처럼 형식을 지정할 수 있다.
• 열거형 클래스도 클래스이기 때문에 클래스의 모든 형식 규칙이 적용된다.

private enum Answer {
  YES {
    @Override public String toString() {
      return "yes";
    }
  },

  NO,
  MAYBE
}

    4.8.2 Variable declarations - 변수선언

• 모든 변수 선언은 하나의 변수만 선언해야한다.
• int a,b; 와 같은 선언은 사용하지 않는다.
• for 반복문의 헤더에서는 예외적으로 여러 변수 선언이 허용된다.
  
  
• 지역 변수는 습관적으로 이를 포함하는 블록이나 블록같은 구조의 시작 부분에서 선언되지 않는다.
• 범위를 최소화하기 위해서 처음 사용되는 지점에 가깝게 선언된다.
• 지역 변수 선언은 일반적으로 이니셜라이저가 있거나 선언 직후에 초기화 한다.

    4.8.3. Arrays

4.8.3.1 Array initializers: can be "block-like"

• 배열 이니셜라이저는 블록처럼 사용될 수 있다.
• 모든 배열 이니셜라이저는 블록처럼 선택적으로 형식을 지정할 수 있다. 다음 아래의 모든 예는 유효한 배열 이니셜라이저의 예이다. 

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.3.2 No C-style array declarations

• 대괄호는 변수가 아니라 자료형에 붙여서 사용한다. String args[] (x) ->  String[] args

    4.8.4 Switch statements

• 스위치 블록의 들여쓰기는 2개의 추가 공백을 사용한다.
• 또한 각 case 내의 구문을 쓸때는 들여쓰기를 +2 의 추가 공백을 사용하며 다음 case로 넘어갈 때는 이전의 수준으로 돌아간다. 
• 각 case 에서 break 가 없이 통과하는 경우에는 일반적으로 //fall though 라는 주석을 달아놓는다.
• case 1 처럼 빈 case 의 경우에는 주석을 사용하지 않아도 된다.
• switch 문에 default 코드가 없는 경우에도 default 블록을 빈 코드로 추가한다.

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

    4.8.5 Annotations

4.8.5.1 Type-use annotations

• Type-use 어노테이션은 자료형 이전에 바로 나온다. 
• @Target(ElementType.TYPE_USE) 이 포함된 어노테이션은 type-use 어노테이션이다. 
• 어노테이션은 각 한줄에 적으며 들여쓰기를 하지 않는다.
• 파라미터가 없는 하나의 어노테이션의 경우 메소드 시그니쳐와 같이 쓸수 있으며 필드 변수에 붙이는 어노테이션의 경우에도 한 줄에 여러개를 쓸 수 있다. 
• 허용되는 예

final @Nullable String name;
public @Nullable Person getPersonByName(String name);

@Deprecated
@CheckReturnValue
public final class Frozzler { ... }

@Deprecated
@Override
public String getNameIfPresent() { ... }

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

@Partial @Mock DataLoader loader;

 

    4.8.6 Comments

• 모든 줄바꿈 앞에는 임의의 공백이 오고 그 뒤에 구현주석이 달린다. 이러한 주석은 공백으로 랜더링되지 않는다.
• 블록 주석은 주변 코드와 같은 수준으로 들여쓰기 된다. /* ... */ , // ... 의 스타일로 작성할 수있으며 여러 행일 경우에는  /* ... */ 의 스타일을 사용한다.  다음 라인은 '*' 와 함께 시작되어야 한다. 

/*
 * This is          // And so           /* Or you can
 * okay.            // is this.          * even do this. */
 */

 

    4.8.7 Modifiers

• 클래스나 멤버 수정자가 존재하는 경우 Java 언어에서 권장하는 순서로 나타난다.
• public > protected > private > abstract > default > static > final > transient > volatile > synchronized > native > strictfp

    4.8.8 Numeric Literals

• Long 타입의 정수는 대문자인 L을 사용하며 소문자는 절대 사용하지 않는다.

 

5. 명명

5.1. 모든 식별자에 공통되는 규칙

• 식별자들은 오직 ASCII 문자 혹은 숫자,언더바를 이용한다.
• 구글 스타일에서는 아래와 같은 예처럼 특수 접두나사 접미사를 붙여서사용하지 않는다. 
• 사용 금지 : name_, mName, s_name, kName

 

5.2. 식별자 유형별 규칙

    5.2.1 Package names

• 패키지명은 오직 소문자와 숫자로만 사용한다.
• ex) myjava

    5.2.2 Class names

• 클래스명은 UpperCamelCase 를 사용한다.
• 클래스명은 일반적으로 명사나 명사 구를 사용하지만 상황에 따라 형용사나 형용사구를 사용하기도 한다.
• 어노테이션 클래스에 대해서는 클래스명을 위한 특별한 규칙이나 잘 정의된 컨벤션이 존재하지 않는다.
• 테스트 클래스는 Test 로 끝나는 이름을 같는다. 특정 클래스의 테스트 클래스는 해당 클래스명 +Test 로 테스트 클래스의 이름을 정의한다.

    5.2.3 Method names

• 메소드명은 lowerCamelCase 를 사용한다. 
• 일반적으로 동사를 사용한다.
• JUnit 테스트 메소드를 정의하는 데에는 정답은 없지만 언더바를 통해 논리적인 요소를 구분할 수 있다.

    5.2.4 Constant names

• 상수명은 UPPER_SNAKE_CASE 를 사용한다.
• 모든 문자를 대문자로 사용하는 것을 말하며 각각의 단어는 언더바를 통해 구분한다.
• 상수란 아예 변경되지 않으며 메소드의 영향을 받지 않는 정적인 필드이다. 기본형, 문자열, 변경할 수 없는 값,null 등에 대한
• 모든 예를 보여준다.
  • 어떤 인스턴스이던지 변경될 소지가 있는 경우 그것은 상수가 아니다.
  • 객체를 변경하지 않으려는 의도만으로는 충분하지 않다. 

// Constants
static final int NUMBER = 5;
static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");
static final Map<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 = {};

// 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.2.5 Non-constant field names

• 상수가 아닌 필드명은 lowerCamleCase 를 사용한다.
• 이 이름들은 일반적으로 computedValues, index 처럼 명사를 사용한다.

    5.2.6 Parameter names

• 파라미터의 이름은 lowerCamelCase 르 적어지며 public 메소드에서 한글자의 파라미터는 피해야한다.

    5.2.7 Local variable names

• 지역변수는 lowerCamelCase 를 사용한다. 만약 final 이고 변경할 수 없는 경우에도 상수로 취급되지 않으며 상수의 style 을 적용하면 안된다.

    5.2.8 Type variable names

1. 하나의 대문자나 혹은 하나의 숫자까지 허용한다. (E, T, X, T2)
2. 클래스에 사용되는 형식의 이름에 대문자 T를 붙인다. (RequestT, FooBarT)

 

6.프로그래밍 중 컨벤션

6.1. @Override: 항상 사용

• 오버라이드 한 경우 @Override 어노테이션을 꼭 붙여야 한다.
• 여기에는 상위 클래스의 메소드를 오버라이드한 메소드, 인터페이스를 구현한 메소드, 상위 인터페이스의 메소드를 재지정하는 인터페이스 메소드를 포함한다.
• 단, 부모의 메소드가 @Deprecated 인 경우, @Override 는 생략할 수 있다.

 

6.2. 발견된 예외: 무시하지 않음

• 아래 표기한 내용을 제외하고 catch 문 내에 아무 내용도 없는 경우 중 대부분은 잘못되어 있는 것이다.
• 만약 catch  문이 비어있는 것이 정말 올바르게 작성한 것이라면 이를 주석을 통해 비어있는 것이 왜 올바른지에 대해서 설명해야 한다.
• 하지만 예외와 관련된 테스트를 하는 경우 (예시에 표기된 내용) 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);

// 예외 경우
try {
  emptyStack.pop();
  fail();
} catch (NoSuchElementException expected) {
}

 

6.3. Static members (정적 멤버) : 클래스를 사용하여 자격 부여

• static 클래스 멤버를 참조해야 하는 경우, 그 클래스의 참조나 표현식이 아니라 클래스 자체의 이름으로 참조해야 한다.

Foo aFoo = ...;
Foo.aStaticMethod(); // good
aFoo.aStaticMethod(); // bad
somethingThatYieldsAFoo().aStaticMethod(); // very bad

 

6.4. Finalizers (종료자): 사용되지 않음

• finalize 는 일반적으로 거의 재정의 되지 않는다. 
• Tip : 하지 마라. 만약 너가 정말 해야겠다면 먼저 Effective Java Item 8의 "Avoid finalizers and cleaners  very carefully"를 읽고 이해한 후에 사용하지 마라.

 

7. javadoc

7.1. formate

    7.1.1 General form

• Javadoc 블록의 일반적인 형태는 아래와 같다. 일반적인 아래의 형태는 언제나 적용될 수 있다.
• 또한, 전체의 Javadoc 블록이 한 줄에 들어갈 수 있다면 이는 한줄의 형태로 변경할 수 있다.
• 다만 이때는 @return 과 같은 태그가 존재하면 안된다.

/**
 * Multiple lines of Javadoc text are written here,
 * wrapped normally...
 */
public int method(String p1) { ... }

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

    7.1.2 Paragraphs

• 하나의 빈 줄, 즉 정렬된 (*) 를 포함하는 라인은 문단 사이, 만약 블록 태그 그룹이 있는 경우 그 앞에 나타난다.

    7.1.3 Block tags

• 모든 표준 블록태그는 @param, @return , @throws, @deprecated 순으로 나타나며 이 네가지 유형은 꼭 이에 대한 설명을 덧붙여야한다.
• 블록 태그가  한 줄에 맞지 않으면 연속되는 줄은 '@' 를 기준으로 4개의 들여쓰기를 해준다.

 

7.2. summary fragment

• Javadoc 은 간단한 요약 부분으로 시작된다.
  • /** Returns the customer ID. */ 같은 형식으로 완전한 문장이 아니면서 간단한 요약으로 구성해야 한다.
• 이 부분은 명사로 구성되며 완전한 문장이 아니다.
  • This method is~~, This method returns ~~~ , A {code} is~~~ 처럼 작성되지 않는다.
  • 또한 @return 같은 블록태그도 사용하면 안된다.

 

7.3. whrere use javadoc

• 아래의 예시를 제외하고 모든 public 클래스, 모든 public 혹은 protected 된 멤버에는 최소한 Javadoc이 존재해야 한다.

    7.3.1 Exception: self-explanatory members

• 단순하고 명백한, 즉 메소드명 만으로도 해당 메소드가 어떤 작업을 하는지 정확하게 알 수 있는 경우 Javadoc이 필요하지 않다.
• 용어 자체가 어려워서 모를 수 있는 경우에는 Javadoc 을 생략하면 안된다.

    7.3.2 Exception: overrides

• 상위 메소드를 override 하는 경우에 Javadoc이 항상 존재하는 것은 아니다.

    7.3.4 Non-required Javadoc

• 다른 클래스나 멤버는 Javadoc이 필요하거나, 원할 때 사용된다.
• 구현 주석이 클래스나 멤버의 모든 행동이나 목적을 정의하기 위해 사용된 경우에는 해당 주석은 Javadoc 으로 대신 작성된다.
• 7.1.1,7.1.2,7.1.3,7.2 에서 언급한 불필요한 주석에 대한 규칙은 권장되기는 하지만 강력하게 요구되는 사항은 아니다.

 

 

 

참고 자료

• https://velog.io/@ozragwort/JAVA-%EC%BD%94%EB%94%A9-%EC%BB%A8%EB%B2%A4%EC%85%98%EC%97%90-%EB%8C%80%ED%95%B4%EC%84%9C
• https://velog.io/@cjllee/%EC%9E%90%EB%B0%94-%ED%8C%8C%EC%9D%BC%EC%9D%B4%EB%9E%80
• https://dev-dongmoo.tistory.com/9