■ 주석의 개념

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

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

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

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

    - 특수문자(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님의 틀이부#프로그래밍언어통


저작자 표시 비영리 동일 조건 변경 허락
신고
Posted by 우너효