5편. 주석

주석(Comments)

주석이란, 자신이 작성한 코드를 다른 사람이 이해하기 쉽게 돕는 역할을 하며 수천 줄이 넘어가는 코드에서 자칫하면 자신이 무엇을 하는 코드를 작성했는지 가끔 깜빡할 때도 있어서 중간중간에 주석을 달기도 합니다. 주석은 코드에 영향을 미치지 않으며 컴파일 대상에서 제외됩니다. 즉, 주석 안에서 무엇을 쓰든 결과에 영향을 미치지 않습니다.

구현 주석(Implementation comments)

구현 주석은 그 코드에 관한 주석이나 머릿속에서 떠올린 다소 복잡한 여러 줄의 코드에 관해 보충 설명하고 싶을 때 사용합니다. 구현 주석에는 행 단위 주석과, 블록 단위 주석이 있습니다. 행(line) 단위 주석은 말그대로 한 줄씩 주석 처리가 가능하고, 블록(block) 단위 주석은 여러 줄을 한꺼번에 주석 처리가 가능합니다.

행 단위 주석

행 단위 주석은 //로 시작합니다. 다음은 행 단위 주석의 예입니다.

public class JavaTutorial4 {

	public static void main(String[] args) {
		int num1; // 10진수 정수형 변수 num1 선언
		int num2; // 10진수 정수형 변수 num2 선언
		int result; // 10진수 정수형 변수 result 선언

		num1 = 100; // num1에 100이란 값 대입
		num2 = 200; // num2에 200이란 값 대입
		result = num1 + num2; // result에 num1과 num2을 서로 더하여 나온 값을 대입

		System.out.println(result); // result의 결과를 출력
	}

}

블록 단위 주석

블록 단위 주석은 /*와 */로 감싸서 표현합니다. 복잡한 코드를 설명하거나 여러 줄의 코드를 주석 처리하는데 주로 사용됩니다. 다음은 블록 단위 주석의 예입니다.

/*
 다음의 프로그램은 변수 num1과 num2에 각각 값을 대입하여 
 두 변수의 값을 더한 결과를 result에 저장하고 출력시키는 예제입니다.
*/

public class JavaTutorial4 {

	public static void main(String[] args) {
		int num1;
		int num2;
		int result;

		num1 = 100;
		num2 = 200;
		result = num1 + num2;

		System.out.println(result);
	}

}

문서 주석(Doc comments)

소스 코드가 없어도 되는 개발자들을 위해서 어떻게 구현했는지보다는 어떻게 사용해야 하는지에 대해 작성하고 싶을 때 문서 주석을 사용합니다. 문서 주석은 /**로 시작하고 */로 끝나며, 블록 단위 주석인 /* ... */와는 다름을 주의하세요. 이렇게 작성한 문서 주석은 javadoc을 사용해 이곳과 같이 HTML 형식의 자바 코드 문서를 만들 수 있습니다.

/**
 * x가 한 자리 정수인지 여부를 검사합니다.
 *
 * @param x 검사할 정수
 * @return x가 한 자리 정수라면 참을, 아니라면 거짓을 반환합니다.
 */
public static boolean isSingleDigit(int x) {
	// ...
}

명령 프롬프트에서 자바독 실행하기

자바독(javadoc)은 JDK 내에 포함되어 있으므로 1편에서 환경 변수만 제대로 설정했다면 명령 프롬프트에서 자바독을 실행할 수 있습니다. 먼저, 단축키 Ctrl+R을 눌러 실행 창을 띄우고 cmd를 입력합니다. 그리고 자바 소스 파일이 있는 위치로 이동하여 아래와 같이 입력하면 자바독 문서를 만들 수 있습니다. 첫 번째는 자바독 문서가 생성될 경로이고, 두 번째는 자바 소스 파일의 경로를 적어주시면 됩니다.

javadoc -d C:/doc Main.java

그럼 아래와 같이 자바독 문서가 생성된 것을 볼 수 있습니다.

이클립스에서 자바독 실행하기

먼저, Package Explorer에서 원하는 프로젝트나 패키지에 오른쪽 클릭을 한 뒤에 'Export'를 누릅니다. 그러면 아래와 같은 창이 등장할 것입니다. 그러면 'Java -> Javadoc'을 선택하고 'Next >' 버튼을 누릅니다.

그러면 기본적으로 소스 코드 전체가 선택되어 있을텐데 자바독 문서를 생성하고 싶은 소스 코드를 선택합니다. 아래에서 가시성(visibility)을 설정 후, 'Use standard doclet'의 'Destination'에서 문서가 저장될 경로를 지정합니다. 그 후 'Next' 버튼을 누릅니다.

여기서 'Document title'을 체크하고 문서 제목을 적절하게 입력해줍니다. 그 후 'Finish' 버튼을 누릅니다. 그러면 우리가 지정했던 경로에 문서가 제대로 생성되었음을 확인하실 수 있습니다.