Qual é a diferença entre
/**
* comment
*
*
*/
e
/*
*
* comment
*
*/
em Java? Quando devo usá-los?
O primeiro formulário é chamado Javadoc . Você usa isso ao escrever APIs formais para o seu código, que são gerados pela javadoc
ferramenta. Por exemplo, a página da API Java 7 usa Javadoc e foi gerada por essa ferramenta.
Alguns elementos comuns que você vê no Javadoc incluem:
@param
: é usado para indicar quais parâmetros estão sendo passados para um método e qual valor eles devem ter
@return
: é usado para indicar qual resultado o método retornará
@throws
: é usado para indicar que um método lança uma exceção ou erro no caso de determinada entrada
@since
: é usado para indicar a versão Java mais antiga em que esta classe ou função estava disponível no
Como exemplo, aqui está o Javadoc para o compare
método de Integer
:
/**
* Compares two {@code int} values numerically.
* The value returned is identical to what would be returned by:
* <pre>
* Integer.valueOf(x).compareTo(Integer.valueOf(y))
* </pre>
*
* @param x the first {@code int} to compare
* @param y the second {@code int} to compare
* @return the value {@code 0} if {@code x == y};
* a value less than {@code 0} if {@code x < y}; and
* a value greater than {@code 0} if {@code x > y}
* @since 1.7
*/
public static int compare(int x, int y) {
return (x < y) ? -1 : ((x == y) ? 0 : 1);
}
O segundo formulário é um comentário em bloco (várias linhas). Você pode usar isso se desejar ter várias linhas em um comentário.
Eu direi que você só deseja usar a última forma com moderação ; ou seja, você não deseja sobrecarregar seu código com comentários de bloco que não descrevam quais comportamentos a função de método / complexo deve ter.
Como o Javadoc é o mais descritivo dos dois, e você pode gerar documentação real como resultado do uso, o Javadoc seria mais preferível do que simples comentários em bloco.
Para a linguagem de programação Java , não há diferença entre os dois. Java possui dois tipos de comentários: comentários tradicionais (
/* ... */
) e comentários de final de linha (// ...
). Veja a especificação da linguagem Java . Assim, para a linguagem de programação Java, tanto/* ... */
e/** ... */
são instâncias de comentários tradicionais, e ambos são tratados exatamente da mesma pelo compilador Java, ou seja, eles são ignorados (ou mais corretamente: eles são tratados como espaços em branco).No entanto, como programador Java, você não usa apenas um compilador Java. Você usa uma cadeia de ferramentas inteira, que inclui, por exemplo, o compilador, um IDE, um sistema de construção etc. E algumas dessas ferramentas interpretam as coisas de maneira diferente do compilador Java. Em particular, os
/** ... */
comentários são interpretados pela ferramenta Javadoc, incluída na plataforma Java e gera documentação. A ferramenta Javadoc varrerá o arquivo de origem Java e interpretará as partes/** ... */
como documentação.Isso é semelhante a tags como
FIXME
eTODO
: se você incluir um comentário como// TODO: fix this
ou// FIXME: do that
, a maioria dos IDEs destacará esses comentários para que você não os esqueça. Mas para Java, são apenas comentários.fonte
javadoc
ferramenta não pode interpretar algo.O primeiro são os comentários do Javadoc. Eles podem ser processados pela
javadoc
ferramenta para gerar a documentação da API para suas classes. O segundo é um comentário de bloco normal.fonte
A leitura da seção 3.7 do JLS explica bem tudo o que você precisa saber sobre comentários em Java.
Sobre sua pergunta,
O primeiro
é usado para declarar a tecnologia Javadoc .
Para mais informações,
Doclet
consulte a API .O segundo, conforme explicado claramente no JLS, ignorará todo o texto entre
/*
e,*/
portanto, é usado para criar comentários de várias linhas.Algumas outras coisas que você pode querer saber sobre comentários em Java
/* and */
não tem significado especial nos comentários que começam com//
.//
não tem significado especial nos comentários que começam com/* or /**
.Assim, o texto a seguir é um único comentário completo:
fonte
Eu não acho que as respostas existentes abordaram adequadamente essa parte da pergunta:
Se você estiver escrevendo uma API que será publicada ou reutilizada em sua organização, escreva comentários abrangentes sobre Javadoc para cada
public
classe, método e campo, bem comoprotected
métodos e campos de não-final
classes. O Javadoc deve abranger tudo o que não pode ser transmitido pela assinatura do método, como pré-condições, pós-condições, argumentos válidos, exceções de tempo de execução, chamadas internas etc.Se você estiver escrevendo uma API interna (que é usada por diferentes partes do mesmo programa), o Javadoc é sem dúvida menos importante. Mas, para o benefício dos programadores de manutenção, você ainda deve escrever o Javadoc para qualquer método ou campo em que o uso ou significado correto não seja imediatamente óbvio.
O "recurso matador" do Javadoc é que ele está intimamente integrado ao Eclipse e outros IDEs. Um desenvolvedor só precisa passar o ponteiro do mouse sobre um identificador para aprender tudo o que precisa saber sobre ele. A referência constante à documentação se torna uma segunda natureza para desenvolvedores Java experientes, o que melhora a qualidade de seu próprio código. Se sua API não estiver documentada com Javadoc, desenvolvedores experientes não desejarão usá-la.
fonte
Os comentários na lista a seguir do Código Java são os caracteres acinzentados:
A linguagem Java suporta três tipos de comentários:
O compilador ignora tudo, de
/*
até*/
.Isso indica um comentário da documentação (comentário do documento, para abreviar). O compilador ignora esse tipo de comentário, assim como ignora os comentários que usam
/*
e*/
. A ferramenta javadoc do JDK usa comentários de documentos ao preparar a documentação gerada automaticamente.O compilador ignora tudo, desde
//
o final da linha.Agora, sobre quando você deve usá-los:
Use
// text
quando quiser comentar uma única linha de código.Usar
/* text */
quando quiser comentar várias linhas de código.Use
/** documentation */
quando desejar adicionar algumas informações sobre o programa que podem ser usadas para geração automática de documentação do programa.fonte
O primeiro é para Javadoc, que você define no topo de classes, interfaces, métodos etc. Você pode usar Javadoc como o nome sugere para documentar seu código sobre o que a classe faz ou o que método faz, etc., e gera um relatório sobre ela.
O segundo é o comentário do bloco de código. Digamos, por exemplo, que você tenha algum bloco de código que não deseja que o compilador interprete, use o comentário do bloco de código.
outro é // isto você usa no nível da instrução para especificar o que as linhas de códigos seguintes devem fazer.
Existem alguns outros também como // TODO, isso marcará que você deseja fazer algo mais tarde nesse local
// FIXME você pode usar quando tiver alguma solução temporária, mas quiser visitar mais tarde e torná-la melhor.
Espero que isto ajude
fonte
fonte
Java suporta dois tipos de comentários:
/* multiline comment */
: O compilador ignora tudo, de/*
até*/
. O comentário pode se estender por várias linhas.// single line
: O compilador ignora tudo, desde//
o final da linha.Algumas ferramentas, como o javadoc, usam um comentário especial de múltiplas linhas para sua finalidade. Por exemplo,
/** doc comment */
é um comentário de documentação usado pelo javadoc ao preparar a documentação gerada automaticamente, mas para Java é um simples comentário de múltiplas linhas.fonte
/** .. */
é apenas um comentário multilinha regular, e o primeiro caractere dentro dele passa a ser um asterisco.