Comentários

Comentários são textos que não são compilados, usados para melhorar a legibilidade do código e fornecer informações sobre sua lógica e funcionamento. Apesar disso, devem ser utilizados com parcimônia. Antes de adicionar um comentário, é uma boa prática verificar a sua necessidade garantindo que não esteja apenas descrevendo o funcionamento óbvio do código. Uma sugestão é utilizar comentários para descrever a regra de negócio envolvida quando a complexidade exigir. Dito isso, em Java, existem duas maneiras de criar comentários: de linha única e de múltiplas linhas.

Comentário de Linha Única

Um comentário de linha única começa com " // " e pode ser usado em qualquer lugar no código para adicionar uma explicação sobre o que o código faz. Tudo que segue as barras duplas é considerado um comentário e será ignorado pelo compilador.

int x = 5; // atribui 5 à variável x

Comentário de Múltiplas Linhas

Um comentário de múltiplas linhas é delimitado por "/" no início e "/" no final e é usado para comentar várias linhas de código. Isso é útil para explicar blocos inteiros de código ou desabilitar temporariamente o código sem ter que excluí-lo.

/*
Este é um comentário de múltiplas linhas
que abrange várias linhas de código.
Ele pode ser usado para desabilitar blocos de código ou
para adicionar uma descrição de como o código funciona.
*/

Comentários Javadoc

Os comentários Javadoc são usados para criar documentação para o código Java. Eles começam com "/**" e terminam com "*/". Os comentários Javadoc podem incluir tags especiais para documentar métodos, classes, variáveis e pacotes.

/**
* Esta é uma descrição de um método que retorna a soma de dois números.
* @param num1 O primeiro número a ser adicionado.
* @param num2 O segundo número a ser adicionado.
* @return A soma de num1 e num2.
*/
public int somar(int num1, int num2) {
  return num1 + num2;
}

Comentários de Depreciação

Os comentários de depreciação são usados para informar aos usuários do código que um método, classe ou variável está obsoleto e pode ser removido em versões futuras. Eles são criados com a tag "@deprecated".

/**
* Este método está obsoleto e não deve ser usado. Use o método somar() em vez disso.
* @deprecated
*/
public void antigoMetodo() {
  // código do método antigo
}

Referências

Java Comments

Comentário em java - Javatpointwww.javatpoint.com