/ ** e / * em Java Comentários

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 javadocferramenta. 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 comparemé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 FIXMEe TODO: se você incluir um comentário como // TODO: fix thisou // 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.

O primeiro são os comentários do Javadoc. Eles podem ser processados ​​pela javadocferramenta para gerar a documentação da API para suas classes. O segundo é um comentário de bloco normal.

A leitura da seção 3.7 do JLS explica bem tudo o que você precisa saber sobre comentários em Java.

Existem dois tipos de comentários:

• / * texto * /

Um comentário tradicional: todo o texto dos caracteres ASCII / * para os caracteres ASCII * / é ignorado (como em C e C ++).

• //texto

Um comentário de fim de linha: todo o texto dos caracteres ASCII // até o final da linha é ignorado (como em C ++).

Sobre sua pergunta,

O primeiro

/**
 *
 */

é usado para declarar a tecnologia Javadoc .

Javadoc é uma ferramenta que analisa as declarações e os comentários da documentação em um conjunto de arquivos de origem e produz um conjunto de páginas HTML que descrevem as classes, interfaces, construtores, métodos e campos. Você pode usar um doclet Javadoc para personalizar a saída Javadoc. Um doclet é um programa escrito com a API do Doclet que especifica o conteúdo e o formato da saída a ser gerada pela ferramenta. Você pode escrever um doclet para gerar qualquer tipo de saída de arquivo de texto, como HTML, SGML, XML, RTF e MIF. A Oracle fornece um doclet padrão para gerar a documentação da API no formato HTML. Os doclets também podem ser usados ​​para executar tarefas especiais não relacionadas à produção de documentação da API.

Para mais informações, Docletconsulte 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

• Comentários não aninham.
• /* 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 /**.
• A gramática lexical implica que os comentários não ocorrem entre literais de caracteres ( §3.10.4 ) ou literais de string ( §3.10.5 ).

Assim, o texto a seguir é um único comentário completo:

/* this comment /* // /** ends here: */

Eu não acho que as respostas existentes abordaram adequadamente essa parte da pergunta:

Quando devo usá-los?

Se você estiver escrevendo uma API que será publicada ou reutilizada em sua organização, escreva comentários abrangentes sobre Javadoc para cada publicclasse, método e campo, bem como protectedmétodos e campos de não- finalclasses. 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.

Os comentários na lista a seguir do Código Java são os caracteres acinzentados:

/** 
 * The HelloWorldApp class implements an application that
 * simply displays "Hello World!" to the standard output.
 */
class HelloWorldApp {
    public static void main(String[] args) {
        System.out.println("Hello World!"); //Display the string.
    }
}

A linguagem Java suporta três tipos de comentários:

/* text */

O compilador ignora tudo, de /*até */.

/** documentation */

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.

// text

O compilador ignora tudo, desde //o final da linha.

Agora, sobre quando você deve usá-los:

Use // textquando 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.

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

• Comentário único, por exemplo: // comentário
• Comentário em várias linhas, por exemplo: / * comment * /
• Comentário do javadoc, por exemplo: / ** comment * /

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.