O que são co­men­tá­rios em Java e como criá-los

Há três tipos di­fe­ren­tes de co­men­tá­rios em Java. Você pode usar co­men­tá­rios para es­tru­tu­rar e explicar seu código. Os co­men­tá­rios de linha única são para notas curtas, enquanto os co­men­tá­rios em bloco são adequados para ex­pli­ca­ções mais longas. Os co­men­tá­rios de do­cu­men­ta­ção, por outro lado, são extensos e oferecem valor acima e além do código-fonte.

O que são co­men­tá­rios em Java?

Trabalhar no código-fonte às vezes pode causar problemas, mesmo para de­sen­vol­ve­do­res ex­pe­ri­en­tes. De­pen­dendo do projeto e de seu escopo, as coisas podem se tornar im­pre­vi­sí­veis ra­pi­da­mente 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 in­tui­ti­va­mente.

Para ajudar a evitar mal-en­ten­di­dos e es­tru­tu­rar o código com mais clareza, o Java oferece aos usuários a ca­pa­ci­dade de escrever co­men­tá­rios. Você pode usar co­men­tá­rios nessa linguagem de pro­gra­ma­ção para explicar seu processo de pen­sa­mento, cálculos, métodos, classes ou es­tru­tu­ras. Quando você ou outra pessoa analisar o código pos­te­ri­or­mente, os co­men­tá­rios fa­ci­li­ta­rão o trabalho com o código.

Para garantir que os co­men­tá­rios sejam eficazes, é im­por­tante mantê-los o mais curtos possível. Ao mesmo tempo, eles devem fornecer aos leitores in­for­ma­ções su­fi­ci­en­tes. Na solução de problemas, co­men­tá­rios bem for­mu­la­dos são es­sen­ci­ais.

Os co­men­tá­rios em Java estão dis­po­ní­veis em três versões di­fe­ren­tes: co­men­tá­rios de linha única, co­men­tá­rios em bloco (co­men­tá­rios de várias linhas) e co­men­tá­rios de do­cu­men­ta­ção. Todos os co­men­tá­rios são marcados para que não sejam levados em conta na com­pi­la­ção. Nas seções a seguir, mos­tra­re­mos como criar co­men­tá­rios em Java e quando usar cada um deles.

Que tipos de co­men­tá­rios existem em Java?

De­pen­dendo do tipo de in­for­ma­ção que você deseja escrever, há três tipos di­fe­ren­tes de co­men­tá­rios dis­po­ní­veis em Java. São eles:

Co­men­tá­rios de linha única

Essa é a opção de co­men­tá­rio mais simples. Esse tipo de co­men­tá­rio é criado usando duas barras con­se­cu­ti­vas (//) e não pode ter mais de uma linha. Com co­men­tá­rios de linha única, você não precisa indicar um ponto final, pois ele é au­to­ma­ti­ca­mente alcançado no final da linha. Esse tipo de co­men­tá­rio em Java é adequado para co­men­tá­rios curtos que explicam uma função em poucas palavras.

Co­men­tá­rios de várias linhas

Se suas ex­pli­ca­ções pre­ci­sa­rem ser um pouco mais longas, você pode usar multi-line comments. Te­o­ri­ca­mente, eles podem ser de qualquer tamanho. Eles são adequados para incluir linhas al­ter­na­ti­vas de código que são excluídas da com­pi­la­ção ou para ex­pli­ca­ções de­ta­lha­das. Os co­men­tá­rios de várias linhas são in­tro­du­zi­dos com uma barra e um asterisco (/*). Ao chegar ao final do co­men­tá­rio, basta digitar um asterisco seguido de uma barra (*/). O texto entre a barra in­tro­du­tó­ria e a barra de fe­cha­mento é tratado como um co­men­tá­rio e não é levado em conta na com­pi­la­ção do código.

Co­men­tá­rios da do­cu­men­ta­ção

Embora os co­men­tá­rios de linha única e de várias linhas possam, te­o­ri­ca­mente, ser inseridos em qualquer lugar do código-fonte, os co­men­tá­rios de do­cu­men­ta­ção são sempre colocados di­re­ta­mente antes das classes ou dos métodos que descrevem. Com a ajuda de fer­ra­men­tas, esses co­men­tá­rios são lidos e resumidos na do­cu­men­ta­ção HTML. Eles são usados prin­ci­pal­mente para criar dados meta para autores e de­ter­mi­na­dos tipos de pa­râ­me­tros. Eles são marcados com um símbolo @. Os co­men­tá­rios da do­cu­men­ta­ção são in­tro­du­zi­dos com uma barra e dois as­te­ris­cos (/**) e terminam com um asterisco e uma barra (*/).

Co­men­tá­rios de linha única

Para entender como os co­men­tá­rios em Java funcionam na prática, veremos alguns exemplos simples. Você mesmo pode ex­pe­ri­mentá-los para testar o resultado. Um co­men­tá­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 ins­tru­ções. **. Veja a seguir a aparência do co­men­tá­rio em sua própria linha:

// Example of a single-line comment
class Main {
	public static void main(String[] args) {
	// Here is the comment
	System.out.println("This is the text that will be output at the end.");
	}
}

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 co­men­tá­rios apa­re­ce­rão apenas no código-fonte.

Como al­ter­na­tiva, você pode colocar o co­men­tá­rio di­re­ta­mente após o comando:

// Example of a single-line comment
class Main {
public static void main(String[] args) {
System.out.println("This is the text that is output at the end."); // This is the comment.
	}
}

O po­si­ci­o­na­mento do co­men­tá­rio não altera a saída.

Co­men­tá­rios de várias linhas

Se quiser inserir um co­men­tá­rio de várias linhas em seu código, você poderá incluí-lo antes ou depois das ins­tru­ções em seu código. Os co­men­tá­rios de várias linhas são sempre in­tro­du­zi­dos com uma barra e um asterisco. Aqui está um co­men­tá­rio de várias linhas antes das ins­tru­ções de código:

/* In this example there is a multi-line comment.
It starts after the asterisk.
The actual instructions for the computer are under the comment.
This is the last line of this Java comment.
*/
class Main {
public static void main(String[] args) {
System.out.println("This is the text that will be output at the end.");
	}
}

O resultado é “Este é o texto que será exibido no final”.

Veja como inserir o co­men­tá­rio sob as ins­tru­ções:

// Example of a multi-line comment below the instructions
class Main {
public static void main(String[] args) {
System.out.println("This is the text that will be output at the end.");
/* In this example there is a multi-line comment.
It starts after the asterisk.
The actual instructions for the computer are above the comment.
This is the last line of this Java comment. */
	}
}

O resultado deve ser o mesmo do exemplo anterior. O co­men­tá­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 di­re­ta­mente após o co­men­tá­rio ou usar uma linha separada.

Co­men­tá­rios da do­cu­men­ta­ção

Os co­men­tá­rios de do­cu­men­ta­ção funcionam de forma se­me­lhante aos co­men­tá­rios de bloco, mas são in­tro­du­zi­dos por uma barra e dois as­te­ris­cos. Isso permite que as fer­ra­men­tas de do­cu­men­ta­ção usem os co­men­tá­rios para criar do­cu­men­ta­ção. Se ne­ces­sá­rio, eles também podem conter etiquetas HTML, como <h1>, <p> ou <strong>.

O Javadoc, uma fer­ra­menta popular que você pode usar para ler os co­men­tá­rios da do­cu­men­ta­ção, também usa outras tags úteis. Aqui estão algumas das mais im­por­tan­tes: