Só a título de curiosidade, todos costumam documentar as classes com @author e @version e os métodos com a descrição, o @param e o @return?
E tem mais algum annotation que é muito utilizado, ou muito bom para determinado caso?
Eu sempre gasto 30% do meu tempo de desenvolvimento documentando o que fiz… Isso é bom se alguém vai pegar o seu código para dar manutenção…
além disso eu costumo colocar o e-mail de contato para caso a pessoa q esteja dando manutenção em um codigo q eu fiz tiver alguma duvida poder me perguntar…
Eu já dei manutenção em código sem nem um comentário de linha (//comentario). É como você procurar uma agulha no palheiro à noite. E ainda tem o risco de se machucar com a agulha… :lol: Ótima analogia hein??
@author deveria ficar só no sistema de controle de versões. É meio complicado manter isso junto com os fontes - a tendência é um fulano apagar o seu nome e pôr o dele, o que é meio chato - ou pior, o fulano que faz a manutenção não põe o nome dele, só deixa o seu, e você é que acaba ficando com a culpa.
@version é muito importante ter, já que nem sempre bate com o sistema de controle de versões.
@param e @return são indispensáveis, exceto em “getters” e “setters” triviais, onde o que deveria ser documentado é a “propriedade” correspondente.
@see deveria ser sempre usado, pelo menos para dizer em que parte da sua documentação está a referência para este método ou classe.
Em relação ao @author, a gente sempre usa o LastChangedDate e LastChangedBy do Subversion para evitar estes problemas que o thingol citou.
Se bem que depois de alguns meses, as vezes não faz a menor diferença de quem é o autor.
[quote=thingol]@author deveria ficar só no sistema de controle de versões. É meio complicado manter isso junto com os fontes - a tendência é um fulano apagar o seu nome e pôr o dele, o que é meio chato - ou pior, o fulano que faz a manutenção não põe o nome dele, só deixa o seu, e você é que acaba ficando com a culpa.
@version é muito importante ter, já que nem sempre bate com o sistema de controle de versões.
@param e @return são indispensáveis, exceto em “getters” e “setters” triviais, onde o que deveria ser documentado é a “propriedade” correspondente.
@see deveria ser sempre usado, pelo menos para dizer em que parte da sua documentação está a referência para este método ou classe. [/quote]
Estou em uma micro empresa, e estou fazendo o início do projeto sozinho por enquanto, acredito q outros entrarão depois, e eu não conheço muito sobre documentação, poderia me dizer o que é o “controle de versões” onde deveria estar o @author? E como funciona isso de documentar a “propriedade” dos “getters” e “setters”? Normalmente eu deixo eles sem nada, já q o próprio nome diz “get” ou “set”.
Outra coisa, ainda estou aprendendo, mas eu utilizo o @param e @return da seguinte forma:
@param linha: Linha para criação do dado na tabela
@param coluna: Coluna para criação do dado na tabela
@return Retorna “true” se o dado foi inserido com sucesso.
É esse mesmo o caminho? 
Por exemplo, normalmente você tem em fontes:
/** Fonte usada para o título */
private Font titleFont;
public void setTitleFont (Font theFont) {
titleFont = theFont;
}
public Font getTitleFont() {
return titleFont;
}Como você viu, para setters e getters triviais acho completamente dispensável documentar; mas o problema é que a variável de instância fica como “private” e isso não é mostrado por “default” no JavaDoc. Se você passar o parâmetro ao JavaDoc para ele documentar as variáveis “private”, documenta coisas demais no JavaDoc, incluindo coisas que não deveriam ser mostradas no JavaDoc; então muitas vezes o que se faz é solicitar que se documentem as variáveis “protected” (acho que isso é default) e fazer isto:
/** Fonte usada para o título */
protected Font titleFont;
public void setTitleFont (Font theFont) {
titleFont = theFont;
}
public Font getTitleFont() {
return titleFont;
}Mas na verdade não sei uma resposta boa para esse problema.