Java의 주석: 모든 것이 그렇게 단순하지는 않습니다.

소개

댓글 - 더 간단할 수도 있고 전체 기사를 작성하는 이유도 있을 것 같습니다. 그러나 그렇게 간단하지는 않습니다. 상사가 말했듯이 코드는 누구나 작성할 수 있지만 좋은 댓글을 작성하는 것은 어렵습니다. 대부분의 언어 코스는 전통적인 Hello World로 시작됩니다. Oracle Tutorials 의 "시작하기" 섹션에서도 "Hello World!" 로 시작합니다. 애플리케이션 . 그리고 코드의 첫 번째 줄부터 Java 주석을 볼 수 있습니다. Java Code Convention과 같은 중요한 문서에서 주석이 별도의 섹션인 Comments 로 제공된다는 사실에서도 그 중요성이 강조됩니다 . 문서에 따르면 Java의 주석은 두 가지 유형으로 나뉩니다.

• 구현 주석(또는 코드 주석)
• 코멘트를 문서화하고 있습니다.

코드 주석은 개별 라인/블록을 설명하는 데 사용되며 문서 주석은 구현과 관계없이 코드 사양(인터페이스)을 설명하는 데 사용됩니다. Java 주석은 컴파일러에서 무시됩니다. 사용자가 아니라 개발자에게 의미가 있습니다. 따라서 컴파일된 클래스의 크기를 줄일 수 있습니다.

자바 코드 주석

이름을 보면 이 주석이 코드와 관련되어 있으며 코드의 기능을 반영해야 한다는 것이 분명합니다. 코드 주석은 다음과 같습니다.

• 소문자(즉, 한 줄로 설명)

  // Строчный комментарий
  System.out.println("Hello, World!");




• 블록(즉, 한 줄에 맞지 않기 때문에 전체 블록으로 설명됩니다)

  /*
   * Блочный комментарий
   */
  System.out.println("Hello");

블록 주석의 흥미로운 특징은 " /*- "(예: 별표 뒤에 빼기 기호 추가) 로 시작하면 이 블록 주석의 텍스트 형식이 지정되지 않는다는 것입니다 . 흥미롭지만 특정 주석의 도움으로 몇 가지 IDE 힌트를 제공할 수 있습니다. 예를 들어 Eclipse IDE에서 인라인 주석 " //@formatter:on " 및 " //@formatter:off "를 사용하면 코드 섹션의 형식 지정을 비활성화할 수 있습니다. 주석은 필요한 경우에만 자제해서 사용해야 합니다. 예를 들어, "코드에 주석을 쓰지 마세요!"라는 주제에 대한 기사를 읽을 수 있습니다. . Robert Martin이 쓴 Clean Code: Creating, Analyzing, Refactoring 이라는 훌륭한 책이 있습니다 . 별도의 "댓글" 장이 있습니다. 이 장의 비문으로 Brian W. Kernighan과 P. J. Plower가 쓴 "나쁜 코드에 주석을 달지 말고 다시 작성하세요"라는 훌륭한 인용문이 있습니다. 이 장은 Google Books 에서 볼 수 있습니다 . 일반적인 의미는 그의 인용문으로 표현될 수 있습니다.

댓글을 쓸 때마다 움츠러들고 실패한 것 같은 기분이 든다"고 말했다.

절대적인 진실은 없다는 것이 분명하며 때로는 의견이 필요합니다. 하지만 언제나 선택의 여지가 있으며, 불필요한 댓글은 맞서 싸워야 합니다. 이 장에서는 또한 특이한 주석 TODO에 대해 언급합니다.

// TODO: Добавить World
System.out.println("Hello, ");

요점은 IDE에서 특별한 방법으로 처리할 수 있다는 것입니다. 예를 들어 IDEA에서는 별도의 탭에 수집되어 볼 수 있습니다. 그리고 주석이 포함된 작은 퍼즐: "http://google.com" 줄은 메서드 내부에서 유효한 줄입니다. http는 실제로 태그이고 그 다음에는 주석입니다. 많은 주석이 코드 주석에서 나중에 설명할 문서 주석으로 바뀔 수 있습니다.

문서에 대한 설명

문서 주석은 공개 API를 설명합니다. API 는 애플리케이션 프로그래밍 인터페이스, 즉 다른 개발자가 작업을 수행하는 데 사용할 수 있는 클래스와 메서드입니다. 간단히 말해서, 이러한 주석은 왜 이 클래스와 패키지가 생성되었는지, 그리고 이 메서드나 저 메서드가 수행하는 작업을 설명해야 합니다. 필요한 경우 클래스 필드를 설명할 수도 있습니다. 이것이 바로 JavaDoc 형식의 IDE 툴팁에서 볼 수 있는 내용입니다. 예를 들어: 이 방법으로 들어가면 이 텍스트가 어디에서 왔는지 확인할 수 있습니다. 다시 한 번 Java 코드 규칙: JavaDoc 형식을 올바르게 지정하는 방법에 대한 코드 규칙을 참조하세요 . 이는 블록 주석과 다소 유사하지만 하나의 별표(Asterix 아님) 대신 두 개가 사용됩니다. 위에 JavaDoc의 예가 나와 있습니다. 모든 가능성을 설명하는 것은 의미가 없습니다. 이는 공식 Oracle 문서에 이미 기록되어 있기 때문입니다. 따라서 우리는 공식 JavaDoc 문서의 "태그 설명" 섹션 에서 필요한 모든 것을 살펴봅니다 . Oracle에는 이 주제에 대한 별도의 튜토리얼인 How to Write Doc Comments for the Javadoc Tool 도 있습니다 . IDE의 툴팁은 훌륭하지만 실제로는 문서인 데에는 이유가 있습니다. 이러한 JavaDoc 주석을 기반으로 문서가 생성됩니다. 이를 위한 특별한 javadoc 유틸리티가 있습니다 . 보시다시피 해당 튜토리얼에서는 이에 대해 설명합니다. 이를 사용하는 방법에 대한 설명은 JavaDoc 의 공식 Oracle 웹사이트에 있습니다 . 이것이 어떤 모습인지 직접 확인하려면 패키지 이름으로 디렉터리에 하위 디렉터리를 생성하면 됩니다(예: test ) . 주석이 포함된 간단한 클래스를 만듭니다. 예를 들어:

package test;

/**
 * This is a JavaDoc class comment
 */
public class JavaDocTest {

  /**
   * This is a JavaDoc public field comment
   */
  public static final String HELLO_MESSAGE = "Hello, World!";

  public static void main(String... args) {
    JavaDocTest.greetings();
  }

  /**
   * This is a JavaDoc public method comment
   */
  public static void greetings() {
    System.out.println(HELLO_MESSAGE);
  }
}

그런 다음 패키지 디렉터리가 포함된 디렉터리에서 다음 명령을 실행할 수 있습니다. javadoc -d ./test test 그런 다음 문서 생성 프로세스를 볼 수 있습니다. 그런 다음 index.html을 열어 생성된 문서를 볼 수 있습니다. API 문서가 게시되는 것을 자주 볼 수 있습니다. 예를 들어 Spring Framework API입니다 .

결론

보시다시피 댓글과 같이 겉으로는 단순 해 보이는 것이 실제로는 훨씬 더 복잡한 것으로 밝혀졌습니다. 그러므로 댓글에 시간을 투자하고 따라해 보면 코드가 더 좋아지고 프로그래머로서 더 가치가 높아질 것입니다. #비아체슬라프