@author @version @param @return [RESOLVIDO]

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.

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.

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.