Java에서 주석의 올바른 사용

Java에서는 3가지 유형의 주석을 제공합니다.

한 줄 주석(C++ 스타일)

Java에서 가장 간단한 주석은 한 줄 주석입니다. 두 개의 슬래시로 시작하여 줄 끝에서 끝납니다. 예:

// this is a single-line comment
 
x = 1; // a single-line comment after code

여러 줄 주석(C 스타일)

Java는 여러 줄에 걸쳐 있는 주석 유형도 제공합니다. 이 유형의 주석은 슬래시와 별표로 시작하고 별표와 슬래시로 끝납니다. 이 주석 유형의 시작 및 끝 구분 기호는 같은 줄에 있을 수도 있고 다른 줄에 있을 수도 있습니다. 예:

/* This is a c-style comment */
 
/*  This is also a
 
    c-style comment, spanning
 
    multiple lines */

참고: C 스타일 주석은 중첩될 수 없습니다. 예를 들어, 다음 사용법은 다음과 같습니다.

/* A comment looks like
   /* This is a comment */
   blah blah blah
 */

위 사용법은 Java 컴파일러가 첫 번째 */만 주석으로 처리하기 때문에 구문 오류를 발생시킵니다. (컴파일러는 주석이 첫 번째 "*/"에서 끝나는 것으로 간주합니다).

여러 줄 주석 안에 한 줄 주석을 삽입할 수 있습니다:

/* This is a single-line comment:
 
    // a single-line comment
 
 */

한 줄 주석 안에 여러 줄 주석을 사용할 수 있습니다:

// /* this is
 
//    a multi-line
 
//    comment */

문서 주석

문서 주석은 여러 줄 주석과 매우 유사한 특수 주석으로, 소스 코드에 대한 외부 문서를 생성하는 데 사용할 수 있습니다. 이 주석은 슬래시와 두 개의 별표로 시작하고 별표와 슬래시로 끝납니다. 예를 들면 다음과 같습니다.

/** This is a documentation comment */
 
/** This is also a
 
    documentation comment */

다음은 문서 주석에 대해 참고해야 할 몇 가지 중요한 사항입니다.

javadoc 문서 생성기는 문서 주석의 모든 텍스트를 HTML 단락. 이는 문서 주석 내의 모든 텍스트가 단락 형식으로 지정되고 공백과 줄 바꿈이 무시된다는 의미입니다. 특별한 형식을 원할 경우 문서 주석에 HTML 태그를 사용해야 합니다.

문서 주석이 2개 이상의 별표로 시작하는 경우 javadoc에서는 이러한 별표가 소스 코드의 주석 주위에 "상자"를 만드는 데 사용된다고 가정하고 추가 별표를 무시합니다. 예:

/**********************************
 
   This is the start of a method
 
**********************************/

이 주석에는 "This is the start of a method"라는 텍스트만 유지됩니다.

javadoc은 문서 주석의 줄 시작 부분에 있는 별표를 무시합니다. 예:

/***************************************
 
 * This is a doc comment
 
 * on multiple lines that I want to stand
 
 * out in source code, looking "neat"
 
 ***************************************/

이 댓글에는 "이것은 소스 코드에서 눈에 띄도록 "깔끔하게" 보이고 싶은 여러 줄의 문서 주석입니다."라는 텍스트만 유지됩니다.

일반적인 사용법은 다음과 같습니다.

/******************************************
 
   ...
 
 ******************************************/

댓글을 강조하는 용도입니다. 이는 문서 주석(생각한 것과 다르더라도)이며 주석의 내용은 생성된 문서에 표시됩니다.

문서 주석을 사용해야 하는 경우

적어도 소스 코드의 공용 클래스, 인터페이스, 메서드, 클래스 또는 인스턴스 변수 앞에 문서 주석을 사용해야 합니다. 이를 통해 javadoc은 공용 엔터티와 각 엔터티에 대한 간략한 설명을 나열하는 코드에 대한 간단한 문서를 생성할 수 있습니다. 비공개 메소드보다 먼저 문서 주석을 사용할 수도 있지만 이를 문서화하려면 javadoc 옵션을 사용해야 합니다. 비공개 엔터티에 대한 문서 주석을 사용하는 것은 공용 엔터티보다 덜 중요합니다(해당 인터페이스는 노출되지 않습니다...). 그러나 코드에 주석을 달고 싶다면 문서 주석을 사용할 수도 있습니다.

한 줄 주석을 사용해야 하는 경우

언제든지!

주석과 관련하여 간단한 제안이 있습니다. 일반 주석(클래스, 인터페이스, 메서드 또는 변수를 설명하는 문서 주석이 아님)을 작성하려면 한 줄 주석을 사용하세요.

왜요? 여러 줄 주석을 사용하여 코드 세그먼트를 쉽게 "주석 처리"할 수 있기 때문입니다("코드 주석 처리"는 코드 조각의 어휘 상태를 주석으로 변경하여 컴파일러가 이 코드 조각을 무시할 수 있도록 하는 것을 의미합니다). 예:

x = 1;   /* set x to 1 */
 
y = 2;   /* set y to 2 */
 
f(x, y); /* call f with x and y */

要把上面三行代码注释掉，你可能需要在每一行的前面使用单行注释：

// x = 1;   /* set x to 1 */
 
// y = 2;   /* set y to 2 */
 
// f(x, y); /* call f with x and y */

或者在还没有加注释的地方加上多行注释：

/* x = 1;  */ /* set x to 1 */
 
/* y = 2;  */ /* set y to 2 */
 
/* f(x, y);*/ /* call f with x and y */

或者分解或删除已存在的注释的“结束注释”分解符：

/*
 
x = 1;   /* set x to 1 * /
 
y = 2;   /* set y to 2 * /
 
f(x, y); /* call f with x and y * /
 
*/

这些用法都糟糕透了。如果原始代码使用下面的注释，那么事情就好办多了：

x = 1;   // set x to 1
 
y = 2;   // set y to 2
 
f(x, y); // call f with x and y

如此一来，只需使用多行注释把代码围起来你就可以轻松把它注释掉：

/*
 
x = 1;   // set x to 1
 
y = 2;   // set y to 2
 
f(x, y); // call f with x and y
 
*/

在你需要使用注释的时候尽量使用单行注释，不要写无用的注释。

你也可以看看之前发布的9个最有趣的代码注释，尽管它是搞笑的。

什么时候使用多行注释

阅读了上面的内容后，这个问题变得很明显了。只使用多行注释来注释代码段，不要用以其他目的。