Comentários em Java: nem tudo é tão simples

Introdução

Comentários - parece que poderia ser mais simples, e por que escrever um artigo inteiro. Mas não é tão simples. Como disse meu chefe, qualquer um pode escrever código, mas escrever um bom comentário é difícil. A maioria dos cursos de idiomas começa com o tradicional Hello World. Mesmo nos Tutoriais Oracle, na seção "Introdução", começamos com o "Hello World!" Aplicativo . E desde as primeiras linhas de código nós os vemos - comentários Java. Sua importância também é enfatizada pelo fato de que em um documento tão importante como a Convenção do Código Java, os comentários recebem uma seção separada: Comentários . De acordo com a documentação, os comentários em Java são divididos em dois tipos:

• comentário de implementação (ou comentário de código);
• documentando comentário.

Comentários de código são usados ​​para descrever linhas/blocos individuais, e comentários de documentação são usados ​​para descrever a especificação do código (sua interface) independente de sua implementação. Comentários Java são ignorados pelo compilador porque eles fazem sentido para o desenvolvedor, não para o usuário. Portanto, você pode reduzir o tamanho das classes compiladas.

Comentários do código Java

Pelo nome fica claro que este comentário está relacionado ao código e deve refletir suas características. Os comentários do código são:

• Minúsculas (ou seja, descritas em uma linha)

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




• Bloco (ou seja, são descritos como um bloco inteiro, porque não cabem em uma linha)

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

Uma característica interessante de um comentário em bloco é que se começarmos com “ /*- ” (ou seja, adicionar um sinal de menos após o asterisco), o texto deste comentário em bloco não será formatado. Interessante, mas com a ajuda de alguns comentários você pode dar algumas dicas de IDE. Por exemplo, usando os comentários embutidos " //@formatter:on " e " //@formatter:off " no Eclipse IDE você pode desabilitar a formatação para seções de código. Você precisa usar comentários com moderação e somente quando necessário. Por exemplo, você pode ler um artigo sobre este tópico: “Não escreva comentários no código!” . Existe um ótimo livro chamado Clean Code: Criando, Analisando e Refatorando, de Robert Martin. Possui um capítulo separado “Comentários”. Como epígrafe deste capítulo, uma citação igualmente excelente: “Não comente códigos ruins – reescreva-os” de Brian W. Kernighan e P. J. Plower. Este capítulo pode ser encontrado no Google Livros . O significado geral pode ser expresso em uma citação dele:

Cada vez que você comenta, estremece e se sente um fracasso."

É claro que não existe verdade absoluta e às vezes são necessários comentários. Mas sempre há opções e é preciso combater comentários desnecessários. Este capítulo também menciona comentários incomuns, TODO:

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

A questão é que eles podem ser tratados de uma maneira especial no IDE. Por exemplo, no IDEA eles são coletados em uma guia separada, onde você pode visualizá-los: E um pequeno enigma com um comentário: A linha “http://google.com” é uma linha válida dentro do método, porque http aqui é na verdade uma tag e depois um comentário. Freqüentemente, muitos comentários podem ir de comentários de código a comentários de documentação, sobre os quais falaremos mais tarde.

Comentários para documentação

Os comentários da documentação descrevem a API pública. API é a interface de programação da aplicação, ou seja, aquelas classes e métodos que estão disponíveis para outros desenvolvedores realizarem quaisquer ações. Resumindo, esses comentários devem explicar por que esta ou aquela classe e pacote foram criados e o que este ou aquele método faz. Você também pode descrever campos de classe, se necessário. Isso é exatamente o que vemos nas dicas de nossos IDEs, que estão formatados como JavaDoc. Por exemplo: Se entrarmos neste método, podemos ver de onde vem este texto: Novamente, consulte a Convenção de Código Java: Convenção de Código sobre como formatar corretamente um JavaDoc . Eles são um pouco semelhantes aos comentários em bloco, mas em vez de um asterisco (não Asterix)) dois são usados. Um exemplo de JavaDoc foi fornecido acima. Não adianta descrever todas as possibilidades, pois isso já está escrito na documentação oficial da Oracle. Portanto, veremos tudo o que precisamos na documentação oficial do JavaDoc , seção "Descrições de tags". A Oracle ainda tem um tutorial separado sobre este tópico: Como escrever comentários de documentos para a ferramenta Javadoc . As dicas de ferramentas no IDE são legais, mas na verdade são documentos por um motivo. Com base nesses comentários JavaDoc, a documentação é gerada. Existe um utilitário javadoc especial para isso . Como podemos ver, esse Tutorial fala sobre isso. Uma descrição de como usá-lo está no site oficial da Oracle para JavaDoc . Para ver por si mesmo como é, você pode criar um subdiretório no diretório com o nome do pacote, por exemplo: test . Crie uma classe simples com comentários. Por exemplo:

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);
  }
}

Depois disso, podemos executar o seguinte comando a partir do diretório que contém nosso diretório de pacotes: javadoc -d ./test test Depois disso, veremos o processo de geração da documentação. E então podemos abrir index.html para ver o documento gerado. Freqüentemente, você verá a documentação da API sendo publicada. Por exemplo, API do Spring Framework .

Conclusão

Como podemos ver, algo aparentemente simples como os comentários acaba sendo muito mais complicado na realidade. Portanto, se você dedicar algum tempo aos comentários e segui-los, seu código ficará melhor e você será mais valioso como programador. #Viacheslav