O que são comentários em Java e como criá-los
Há três tipos diferentes de comentários em Java. Você pode usar comentários para estruturar e explicar seu código. Os comentários de linha única são para notas curtas, enquanto os comentários em bloco são adequados para explicações mais longas. Os comentários de documentação, por outro lado, são extensos e oferecem valor acima e além do código-fonte.
O que são comentários em Java?
Trabalhar no código-fonte às vezes pode causar problemas, mesmo para desenvolvedores experientes. Dependendo do projeto e de seu escopo, as coisas podem se tornar imprevisíveis rapidamente e o código pode ficar confuso. Em momentos como esse, talvez você não queira trabalhar em seu código sozinho. Mas mesmo que queira que outras pessoas possam acessar seu código, elas podem não ser capazes de entendê-lo intuitivamente.
Para ajudar a evitar mal-entendidos e estruturar o código com mais clareza, o Java oferece aos usuários a capacidade de escrever comentários. Você pode usar comentários nessa linguagem de programação para explicar seu processo de pensamento, cálculos, métodos, classes ou estruturas. Quando você ou outra pessoa analisar o código posteriormente, os comentários facilitarão o trabalho com o código.
Para garantir que os comentários sejam eficazes, é importante mantê-los o mais curtos possível. Ao mesmo tempo, eles devem fornecer aos leitores informações suficientes. Na solução de problemas, comentários bem formulados são essenciais.
Os comentários em Java estão disponíveis em três versões diferentes: comentários de linha única, comentários em bloco (comentários de várias linhas) e comentários de documentação. Todos os comentários são marcados para que não sejam levados em conta na compilação. Nas seções a seguir, mostraremos como criar comentários em Java e quando usar cada um deles.
Que tipos de comentários existem em Java?
Dependendo do tipo de informação que você deseja escrever, há três tipos diferentes de comentários disponíveis em Java. São eles:
Comentários de linha única
Essa é a opção de comentário mais simples. Esse tipo de comentário é criado usando duas barras consecutivas (//) e não pode ter mais de uma linha. Com comentários de linha única, você não precisa indicar um ponto final, pois ele é automaticamente alcançado no final da linha. Esse tipo de comentário em Java é adequado para comentários curtos que explicam uma função em poucas palavras.
Comentários de várias linhas
Se suas explicações precisarem ser um pouco mais longas, você pode usar multi-line comments. Teoricamente, eles podem ser de qualquer tamanho. Eles são adequados para incluir linhas alternativas de código que são excluídas da compilação ou para explicações detalhadas. Os comentários de várias linhas são introduzidos com uma barra e um asterisco (/*)
. Ao chegar ao final do comentário, basta digitar um asterisco seguido de uma barra (*/)
. O texto entre a barra introdutória e a barra de fechamento é tratado como um comentário e não é levado em conta na compilação do código.
Comentários da documentação
Embora os comentários de linha única e de várias linhas possam, teoricamente, ser inseridos em qualquer lugar do código-fonte, os comentários de documentação são sempre colocados diretamente antes das classes ou dos métodos que descrevem. Com a ajuda de ferramentas, esses comentários são lidos e resumidos na documentação HTML. Eles são usados principalmente para criar dados meta para autores e determinados tipos de parâmetros. Eles são marcados com um símbolo @. Os comentários da documentação são introduzidos com uma barra e dois asteriscos (/**)
e terminam com um asterisco e uma barra (*/)
.
Comentários de linha única
Para entender como os comentários em Java funcionam na prática, veremos alguns exemplos simples. Você mesmo pode experimentá-los para testar o resultado. Um comentário de linha única começa com duas barras e pode estar em sua própria linha ou ser colocado após um conjunto de instruções. **. Veja a seguir a aparência do comentário em sua própria linha:
Se você usar o comando Java System.out.println
, somente a frase “This is the text that is output at the end” será exibida. Os dois comentários aparecerão apenas no código-fonte.
Como alternativa, você pode colocar o comentário diretamente após o comando:
O posicionamento do comentário não altera a saída.
Comentários de várias linhas
Se quiser inserir um comentário de várias linhas em seu código, você poderá incluí-lo antes ou depois das instruções em seu código. Os comentários de várias linhas são sempre introduzidos com uma barra e um asterisco. Aqui está um comentário de várias linhas antes das instruções de código:
O resultado é “Este é o texto que será exibido no final”.
Veja como inserir o comentário sob as instruções:
O resultado deve ser o mesmo do exemplo anterior. O comentário de linha única na primeira linha do trecho de código também não será gerado. Você pode colocar o asterisco e a barra diretamente após o comentário ou usar uma linha separada.
Comentários da documentação
Os comentários de documentação funcionam de forma semelhante aos comentários de bloco, mas são introduzidos por uma barra e dois asteriscos. Isso permite que as ferramentas de documentação usem os comentários para criar documentação. Se necessário, eles também podem conter etiquetas HTML, como <h1>
, <p>
ou <strong>
.
O Javadoc, uma ferramenta popular que você pode usar para ler os comentários da documentação, também usa outras tags úteis. Aqui estão algumas das mais importantes:
Tag | Syntax | Function |
---|---|---|
@author | @author name-text | Adiciona o autor da classe |
@code | {@code text} | Exibe código alternativo, que não é interpretado automaticamente |
@deprecated | @deprecated deprecatedtext | Adiciona um comentário que desaconselha o uso de uma determinada interface |
@param | @param parameter-name-description | Usado para marcar um parâmetro específico |
@see | @see reference | Pode ser usado para fazer referência a outras referências |