Comentários Java

Os comentários fazem parte de um programa que não é executado. O compilador simplesmente ignora os comentários porque eles não foram feitos para isso. Eles são escritos em linguagem “humana” e têm como objetivo explicar o programa, parte do programa, uma única linha ou método para desenvolvedores ou pessoas envolvidas no desenvolvimento. Na maioria das vezes, os comentários são escritos em inglês, é uma espécie de tradição. Neste artigo falaremos sobre comentários em Java e como utilizá-los corretamente para facilitar a vida de você e de seus colegas de equipe.

Comentários Java: por que eles são importantes

Dizem que os programadores são extremamente preguiçosos quando se trata de comentar sobre seu próprio código. No entanto, esta é uma habilidade muito importante, por isso não a subestime, mesmo se você estiver apenas começando a aprender Java. O código bem comentado é muito mais valioso do que o código sem comentários porque esse programa é muito mais fácil de manter. Como grandes projetos são geralmente escritos em Java, comentários competentes também aceleram o desenvolvimento, pois é mais fácil para um programador lidar com o código de outras pessoas. Comentários são necessários para:

• Entenda o código. Seu ou de outra pessoa. Se você acha que não precisa decifrar seu próprio código porque o escreveu, tente abrir um programa relativamente complexo que você escreveu há um mês ou até antes e entenda rapidamente o que, onde e por que você tinha em mente. Os comentários podem ser usados ​​para explicar a lógica de um programa ou bloco de um programa, bem como deixar recomendações para quem trabalhará com seu código posteriormente. Esse tipo de comentário pode ser chamado de explicativo.

• Contendo informações sobre a finalidade dos objetos, parâmetros de entrada e saída (se houver), dados sobre o desenvolvedor e outras coisas importantes relacionadas ao fragmento de código. Esses comentários estão localizados nos cabeçalhos dos módulos, bibliotecas, procedimentos e funções. Eles podem ser chamados de comentários de documentação.

• Controle bugs e melhore o código. Código questionável ou que precisa de melhorias sempre pode ser comentado e revisado posteriormente. Se lhe ocorrer que determinado problema pode ser resolvido de uma forma diferente, mas agora você não tem tempo para isso, escreva essa ideia no comentário. Caso contrário, provavelmente, sob a pressão do novo código, você o esquecerá.

Tipos de comentários em Java

Apesar de você poder escrever tudo e qualquer coisa nos comentários, existem certos tipos de comentários em Java e regras para usá-los. Em Java, os comentários são frios:

• Comentários de linha única
• Comentários de várias linhas
• Comentários sobre a documentação

Comentários de linha única

Os comentários Java mais comuns são comentários de linha única. Para indicar tal comentário, basta colocar uma barra dupla antes do texto // . Comentários de linha única são sinalizados apenas no início do comentário. O comentário continua até o final da linha. Sintaxe:

//here is a single line comment.

Vejamos um exemplo deste tipo de comentários Java:

public class CommentsDemo1 {
   public static void main(String[] args) {
       System.out.println("This text is visible for Java compiler");
       //this text is single line comment
//This one is also single line comment
//they both (and me) are invisible for compiler
   }
}

A saída é: Normalmente, um comentário de linha única está localizado acima ou abaixo do local comentado no programa, ocasionalmente na mesma linha. É importante que fique visualmente claro a que se refere o comentário.

Comentários multilinhas

Às vezes não há linha suficiente para escrever um comentário Java. Por exemplo, você precisa descrever como funciona um método ou uma fórmula complexa que você está implementando. Nesse caso, você pode escrever vários comentários de uma única linha, mas seria mais racional escrever os chamados comentários de várias linhas. Eles estão marcados em ambos os lados com os símbolos /* */ . Sintaxe de comentários multilinhas:

/*This comment
is
Multi line comment
we can describe here
what we need */

Vejamos um exemplo de comentários multilinhas no código

public class RleTest {

   /*
   Run Length Encoding (RLE),  a data compression algorithm
   that replaces repeated characters (series)
   with one character and the number of its repetitions.

   this method is to decode a String using run-length encoding

    */
   private static String decodeRle(String encoded) {
       if (encoded.isBlank()) return "";
       StringBuilder result = new StringBuilder();
       int count = 0;
       char baseChar = encoded.charAt(0);
       for (int i = 1; i <= encoded.length(); i++) {
           char c = i == encoded.length() ? '$' : encoded.charAt(i);
           if (Character.isDigit(c)) {
               count = count * 10 + Character.digit(c, 10);
           } else {
               do {
                   result.append(baseChar);
                   count--;
               } while (count > 0);
               count = 0;
               baseChar = c;
           }
       }
       return result.toString();
   }
   public static void main(String[] args) {
       System.out.println(decodeRle("C3ecddf8"));
   }
}

Comentários sobre a documentação Java

Este é um tipo especial de comentários Java usado para gerar uma página de documentação. Normalmente os desenvolvedores escrevem comentários de documentação usando Javadoc, um gerador de documentação para gerar documentação de API em formato HTML a partir do código-fonte Java. O formato de documentos usado pelo Javadoc é o padrão da indústria para documentar classes Java e os IDEs mais populares, como IntelliJ IDEA e Eclipse, geram Javadoc HTML automaticamente. Os comentários da documentação Java têm a sintaxe abaixo:

/**
Some important Javadoc comments here
You don’t know it yet, but Javadoc rulez

@author  Java Developer
*/

Aqui está um exemplo: é um fragmento da classe Java Short . A propósito, você pode ver qualquer código de classe Java do seu IDE (por exemplo, no IntelliJ IDEA do Windows, basta pressionar ctrl+LBM ou ctrl + b (no Windows) em qualquer nome de classe ou método).

package java.lang;

import jdk.internal.HotSpotIntrinsicCandidate;
import jdk.internal.misc.VM;

/**
* The {@code Short} class wraps a value of primitive type {@code
* short} in an object.  An object of type {@code Short} contains a
* single field whose type is {@code short}.
*
* <p>In addition, this class provides several methods for converting
* a {@code short} to a {@code String} and a {@code String} to a
* {@code short}, as well as other constants and methods useful when
* dealing with a {@code short}.
*
* @author  Nakul Saraiya
* @author  Joseph D. Darcy
* @see     java.lang.Number
* @since   1.1
*/
public final class Short extends Number implements Comparable<Short> {

   /**
    * A constant holding the minimum value a {@code short} can
    * have, -2<sup>15</sup>.
    */
   public static final short   MIN_VALUE = -32768;

   /**
    * A constant holding the maximum value a {@code short} can
    * have, 2<sup>15</sup>-1.
    */
   public static final short   MAX_VALUE = 32767;

   /**
    * The {@code Class} instance representing the primitive type
    * {@code short}.
    */
   @SuppressWarnings("unchecked")

Aqui está o código Java do método println() bem conhecido e amado por todos os novatos com o seguinte comentário:

/**
* Prints a String and then terminate the line.  This method behaves as
* though it invokes {@link #print(String)} and then
* {@link #println()}.
*
* @param x  The {@code String} to be printed.
*/
public void println(String x) {
   if (getClass() == PrintStream.class) {
       writeln(String.valueOf(x));
   } else {
       synchronized (this) {
           print(x);
           newLine();
       }
   }
}

Javadoc tem algumas tags Javadoc especiais marcadas com @ que você pode ver no código acima. O exemplo dessa tag Javadoc é @author que adiciona um nome do autor da classe. Outra tag Javadoc é @since que adiciona um comentário indicando que esta classe é usada desde a versão especificada do Java. Escrever bons documentos Javadoc requer conhecimento e experiência (e paciência!). Você pode encontrar mais informações sobre Javadoc na documentação oficial Como escrever comentários de documentos para a ferramenta Javadoc .

PS: alguns exemplos de comentários engraçados da vida real

/**
*Dear Maintainer
*
*Once you are done trying to 'optimize' this routine,
*and you have realized what a terrible mistake that was,
*please increment the following counter as a warning
*to the next guy.
*
*total_hours_wasted_here = 73
*/

Exception up = new Exception("Something is really wrong.");
throw up;  //ha ha

// When I wrote this, only God and I understood what I was doing
// Now, God only knows

// sometimes I believe compiler ignores all my comments

/**
Always returns true.
*/
public boolean isAvailable() {
return false;
}

Para reforçar o que você aprendeu, sugerimos que você assista a uma vídeo aula do nosso Curso Java