Como usar comentários no código Java

Comentários Java são notas em um arquivo de código Java que são ignoradas pelo compilador e pelo mecanismo de tempo de execução. Eles são usados ​​para anotar o código, a fim de esclarecer seu design e finalidade. Você pode adicionar um número ilimitado de comentários a um arquivo Java, mas existem algumas "práticas recomendadas" a serem seguidas ao usar comentários.

Geralmente, comentários de código são comentários de "implementação" que explicam a Código fonte, como descrições de classes, interfaces, métodos e campos. Geralmente, existem algumas linhas escritas acima ou ao lado do código Java para esclarecer o que ele faz.

Outro tipo de comentário Java é um comentário Javadoc. Os comentários de Javadoc diferem um pouco na sintaxe dos comentários de implementação e são usados ​​pelo programa javadoc.exe para gerar documentação em Java HTML.

É uma boa prática adquirir o hábito de colocar comentários Java em seu código-fonte para melhorar sua legibilidade e clareza para você e outros programadores. Nem sempre é claro instantaneamente o que uma seção do código Java está executando. Algumas linhas explicativas podem reduzir drasticamente a quantidade de tempo que leva para entender o código.

Comentários de implementação em Código Java existem apenas para os humanos lerem. Os compiladores Java não se importam com eles e quando compilando o programa, eles apenas pulam sobre eles. O tamanho e a eficiência do seu programa compilado não serão afetados pelo número de comentários no seu código-fonte.

Os comentários de implementação vêm em dois formatos diferentes:

• Comentários da linha: Para um comentário de uma linha, digite "//" e siga as duas barras com seu comentário. Por exemplo:

   // este é um comentário de linha única
  int achoNúmero = (int) (Math.random () * 10); 

  Quando o compilador se depara com as duas barras, ele sabe que tudo à sua direita deve ser considerado como um comentário. Isso é útil ao depurar um pedaço de código. Basta adicionar um comentário de uma linha de código que você está depurando e o compilador não o verá:

  •  // este é um comentário de linha única
    // int guessNumber = (int) (Math.random () * 10); 

    Você também pode usar as duas barras para fazer um comentário de fim de linha:

  •  // este é um comentário de linha única
    int achoNúmero = (int) (Math.random () * 10); // Um ​​comentário de fim de linha 

• Bloquear comentários: Para iniciar um comentário em bloco, digite "/ *". Tudo entre a barra e o asterisco, mesmo que esteja em uma linha diferente, é tratado como um comentário até que os caracteres "* /" terminem o comentário. Por exemplo:

   /* isto 
  é 
  uma
  quadra
  Comente
  */
  / * então é isso * /
  

Use comentários Javadoc especiais para documentar sua API Java. Javadoc é uma ferramenta incluída no JDK que gera documentação HTML a partir de comentários no código-fonte.

Um comentário do Javadoc em

.Java

/**

*/

*

Coloque esses comentários diretamente acima do método, classe, construtor ou qualquer outro elemento Java que você deseja documentar. Por exemplo:

// myClass.java
/**
* Faça desta uma frase resumida descrevendo sua classe.
* Aqui está outra linha.
*/
públicoclasse minha classe
{
...
}

Javadoc incorpora várias tags que controlam como a documentação é gerada. Por exemplo, o

@param

 / ** método principal
* @param args String []
*/​
públicoestáticovazio main (String [] args)
​{
System.out.println ("Olá, mundo!");
}

Muitas outras tags estão disponíveis no Javadoc e também suporta tags HTML para ajudar a controlar a saída. Consulte a documentação do Java para obter mais detalhes.

• Não exagere. Todas as linhas do seu programa não precisam ser explicadas. Se o seu programa fluir logicamente e nada inesperado ocorrer, não sinta a necessidade de adicionar um comentário.
• Recue seus comentários. Se a linha de código que você está comentando for recuada, verifique se o seu comentário corresponde à indentação.
• Mantenha os comentários relevantes. Alguns programadores são excelentes na modificação de código, mas, por algum motivo, esqueça de atualizar os comentários. Se um comentário não se aplicar mais, modifique-o ou remova-o.
• Não aninhe comentários em bloco. O seguinte resultará em um erro do compilador:

   /* isto 
  é
  / * Este comentário em bloco termina o primeiro comentário * /
  uma
  quadra
  Comente
  */