자바 주석 작성방법 (Javadoc으로 뽑아내기 위한)

■ 주석의 개념

    - 코드에 대한 개요와 코드 자체만 가지고 이용할 수 없는 추가적인 정보 제공

    - 프로그램을 읽는 것과 이해하는 것에 관계된 정보만을 포함하고 있어야 한다.

    - 중복된 주석은 피해야 한다.

    - 주석을 추가해야만 할 정도의 프로그램이라면 재작성을 고려해야 한다.

    - 특수문자(Form feed, backspace 등)를 포함하면 안된다.

■ 주석의 종류 

    - 문서주석 : '/**      */'에 의해 경계가 결정, javadoc 툴을 사용하여 HTML 파일로 축출

    - 구현주석 : '/*      */'과 '//'에 의해 경계가 결정, 개별적 구현에 대한 주석, 코드와는 상관없는 주석

■ 문서주석

    - 자바 클래스, 인터페이스, 생성자, 메서드, 필드 들을 성명

    - 주석 경계기호인 '/**  */' 안에 들어감

    - 클래스, 인터페이스, 맴버 당 하나씩 들어감

    - 선언 바로 전에 나와야 함.

    - 최 상위 레벨의 클래스와 인터페이스들은 열여쓰기를 하지 않고 멤버들(변수, 메서드)은 들여쓰기를 한다.

    - 클래스에 대한 문서주석의 첫 번째 줄은 들여쓰기를 하지 않고 그 다음에 나오는 문서주석은 별표를 수직으로 맞춘다(1개의 스페이스 포함)

    - 생성자를 포함한 멤버들은 문서주석 첫 줄에서 4개의 스페이스로 들여쓰기를 하고 그 이후는 5개의 스페이스 들여쓰기를 한다.

    - 문서주석에 적절하지 않은 클래스, 인터페이스, 변수, 메서드에 대한 정보를 제공하려면 선언 바로 후에 block 주석이나 single line 주석을 사용한다.(클래스의 구현에 대한 세부사항은 class 선언 다음에 block 주석을 사용)

    - Java는 문서주석을 주석 이후 처음 나오는 선언문과 연결시키므로 문서주석은 메서드, 생성자 정의 블록 내부에 위치하면 안된다.

○ 클래스 설명 주석(Document comments)

    - import 문 다음에 기술

    - 블록주석을 사용

    - 각 라인은 *로 시작

    - 해당 클래스에 대한 기능과 용도 기술

    - <pre>...</pre>내용은 수정하지 않음

    - Serialize 기능이 뭔지 모르겠음.(버전관리 프로그램 관련?)

/**  * Serialize 기능을 사용하여 file에 object를 저장  * <pre>  * input : input.txt   - 입력데이터 파일  * output : output.txt - 출력데이터 파일  * Table : none   * </pre>  *  * <pre>  * <b>History:</b>  *    작성자, 1.0, 2007.3.9 초기작성  * </pre>  *  * @author 최종 수정자  * @version 1.0, 2007.5.5 메서드 추가  * @see    None  */

○ 맴버변수 설명 주석

    - 변수 상단에 위치

    - 블록주석을 사용

    - 용도, 제한사항 등을 기술

    ※ 맴버변수의 기술 순서 : constant - static - primitive - reference

○ 맴버함수 설명 주석

    - 함수의 상단에 위치

    - 블록주석을 사용

    - 메서드 기능설명은 한 두줄로 간결하게 기술

    - 메서드의 파라미터를 type명과 변수명을 적고 간략하게 설명

    - 리턴변수, 예외사항 설명

/**  * 메서드의 기능설명은 한 두줄로 간결하게..  *  * @param int list1 메서드의 파라미터 설명, type명과 변수명을 적고 간략하게 설명  * @return  * @exception 예외사항한 라인에 하나씩  */

○ 기타 주석처리

    - 코드 내부의 짧은 statement 뒤의 주석은 //로

    - 맴버변수 정의시 인자가 많으면 각 인자를 한행에 하나씩 기술, 같은 행에 주석 기재

    - 코드가 산만하지 않게 주석을 멀리 사용

    - /*.........*/는 테스트 목적으로 활용했던 부분을 남김

    - 주석의 시작은 항상 라인의 처음에서 시작하며 각 라인은 *로 시작

    - 블럭내 주석은 사용하지 않는다(특별한 경우 제외)

    - 의문점이나 해결못한 것은 임시주석으로 사용(/*-  ..............*/)

■ 구현주석 : block, single-line, trailing, end of line

○ block 주석

    - 파일, 메서드, 자료구조, 알고리즘의 설명 제공

    - 각각의 파일이 시작될 때와 메서드 전에 사용

    - 메서드 안에 존재하는 block 주석은 설명하는 코드와 같은 레벨로 들여쓰기

    - block 주석의 형식을 고치는 일이 일어나지 않는 특별한 block 주석은 /*- 으로 시작

    - 코드의 나머지로부터 분리하기 위해 처음 한줄은 비워둔다.

/*  * 여기에 block comment 작성  */   /*-  * 형식을 고치지 않는 특별한 block 주석  * 들여쓰기가 무시되는 특별한 주석  * :  * :  */

○ single line 주석

    - 짧은 주석은 뒤에 따라오는 코드와 같은 레벨의 들여쓰기를 하는 한줄로 나타남

    - 한 줄로 써지지 않는다면 block 주석 형식을 따라야 함

if(condition) { /* single line 주석 */ : }     if(condition2){     */ single line 주석 */     ....     }

○ trailing 주석

    - 매우 잛은 주석의 경우 코드와 같은 줄에 나타난다.

    - 코드와의 확실한 구별을 위해 충분히 멀리 떨어뜨림.

if(condition) {                              /* trailing 주석 */ return TRUE ; } else {     return expressionReturn();               /* trailing 주석 */ }

○ end of line 주석

    - 한 줄 모두를 주석처리 하거나 한 줄의 일부분을 주석처리

    - 본문 주석을 위하여 여러 줄에 연속되어 사용하면 안됨

    - 코드섹션을 주석처리 하기 위하여 여러 줄을 연속하여 사용 가능

if(condition) {                          // end of line 주석     expression1 ;     expression2 ; } else {                                   // end of line 주석     expression3 ;     expression4 ; }   // 블럭을 통째로 주석처리 할 경우 // if(condition2) { //     expression5 ; //     expression6 ; // } // else { //     expression7 ; //     expression8 ; // }

■ javadoc로 HTML 문서 생성

    - 개발한 클래스의 모든 설명주석(/* ,.......*/)은 javadoc을 이용하여 HTML 문서 형태로 클래스의 API를 문서화 한다.

    - javadoc은 jdk를 이용한다.

javadoc verbos author version d <대상 디렉토리> <java 소스 파일명>

■ HTML / JavaScript 주석

    - 설명주석 : 블록주석(<!--  ......  // -->)을 사용하며 각 라인은 '*'로 시작한다.

<!   * 사용자 정보 조회 * * history : *           작성자, 1.0, 2006.3.9 초기 작성 * author : 최종수정자 * version : 1.1 2007.3.10 - javascript 함수 추가 * see : 관련된 모듈 기술 * //-->

출처 : Tong - NetSET님의 틀이부#프로그래밍언어통