Você assinou seu código hoje?

Quem utiliza-se ou já utilizou da annotation @author no cabeçalho de seus códigos levanta a mão !

Annotation @author

Desde que comecei a programar no início do segundo semestre de 2004, eu utilizo desse tal de arroba-aútor. Já vi algumas variantes dela, por exemplo:

Annotation @author Augusta edition

Há ainda aqueles que detalham no cabeçalho sua pog contribuição.
Sinceramente eu nunca fui pesquisar se há uma convenção na utilização deste annotation. O fato é que meu uso com isto é descomplicado:

  • Insiro meu nome em novos arquivos;
  • Adiciono meu nome abaixo do último se eu fiz alguma adição ao arquivo, ou;
  • Não adiciono quando faço pequenas modificações sem acrescentar algo de valor ao então domínio/objetivo/proposta do arquivo.

Mas mesmo assim, sempre colocava no formato Nome completo email@provedor

Porém, não pela primeira vez vejo um developer defendendo o não uso deste annotation. A última vez foi numa discussão – no bom sentido – entre @sergioprado e @lfamorim. Com isto, fui perguntar a eles – e alguns outros mais – a opinião pessoal em relação ao tal annotation. Confira:

Eduardo Guerra@emguerra
Obviamente se o uso de @author nas classes for uma prática da equipe irei segui-la sem problemas, mas se a escolha for minha opto por não colocar. Esse tipo de marcação no meu ponto de vista atrapalha a propriedade coletiva do código por determinar explicitamente os autores da classe. No caso de erros na classe, sempre haverão dedos apontando o autor como culpado, mesmo se não foi ele quem introduziu o problema.

Como toda documentação não-executável, pode deixar de ser atualizado com a evolução de um projeto e muitas vezes o autor original não é mais quem mais contribuiu para a classe no seu estado atual. Adicionalmente, sou a favor de manter o código o mais limpo possível e esse tipo de coisa acaba deixando o código de todas as classes mais verboso.

Cainan Costa - @sryche via Jabber
[20:03:08] cainan.costa: não faz sentido, porque o VCS já mostra =P
[20:03:16] cainan.costa: quem é o maluco que fez a parada
[20:03:25] cainan.costa: aí tu usa um git blame
[20:03:33] cainan.costa: e já sabe quem encher de porrada

Lucas Fermando Amorim@lfamorim
Hoje em dia a tag @author é tão obsoleta quanto respeitar um limite de colunas para seu código, mas ainda assim acho elegante e talvez até relevante.

Fica muito mais fácil para aqueles programadores que não usam a IDE XPTO verem o criador de determinado arquivo, método ou função sem ter que recorrer a um programa. É repetitivo você pode alegar, mas eu posso retrucar que a tarefa pode ser automatizada.

Eu aprecio muita essa tag, pois a partir dela posso usando minha humilde IDE identificar o criador de determinados códigos, antecipando os vícios do autor e me adaptando para a leitura. Tudo isso sem abrir a shell e digitar N^C comandos.

N = Familiaridade com o programa X de controle de versão.
C = Commits anteriores.

Christian Benseler - @chrisbenseler
Tenho uma visão que o negócio é "mais embaixo". Antes de tentar assinar um script como seu, o desenvolvedor tem que se preocupar com outros assuntos mais importantes: é um projeto pessoal ou colaborativo? Está prestando serviços a alguém, outra empresa? Qual a política do seu cliente? Qual a versão do script? E qual o tipo de licensa que será adotada?

Só assinar o script não vai fazer a menor diferença se não tiver essas informações. E não vai fazer nenhuma diferença se a comunidade não parar de copiar o script feito por A, retirar os author notes do script e redistribuir o script sem dar esses créditos e/ou sem levar em conta o tipo de licensa adotado.

Carlos Duarte do Nascimento@chesterbr
Antes de mais nada, você se refere a qual linguagem? Em Java, @author pode significar tanto uma anotação em si (e aí depende do contexto), tal como:

@author("chester")

public foo(int bar) {

quanto (o que eu imagino que você queira dizer) a anotação feita em um doclet, i.e.:

  /**
   * Um elemento coberto por JavaDoc.
   * @author chester
   */
	public foo(int bar) {
	…

No segundo caso, eu gosto de @author devido à facilidade em lidar com a autoria coletiva: ela permite anotar classes inteiras ou métodos/atributos particulares; você pode colocar múltiplos autores, e o Eclipse pode ser facilmente configurado para adicioná-la automaticamente. No PHP, se me recordo, é possível usar algo equivalente (phpdoc) em cabeçalhos de código, mas não sei se é válido colocar em métodos/atributos, ou se é possível ter múltiplas declarações no mesmo escopo.

Em qualquer caso, vale notar que sistemas de controle de versão como svn e git são mais eficientes para descobrir quem efetivamente contribuiu com uma classe/método do que esse tipo de tag. Além disso, elas não são suficientes para notas de copyright (ou seja, teriam que ser replicadas apropriadamente para o correto licenciamento do código, independente da licença utlizada), o que limita de fato sua utilidade prática.

Sérgio Prado@sergioprado
Há muito tempo atrás, as ferramentas disponíveis aos programadores eram escassas e limitadas.

Já programei em Assembly com um DOS rodando num x86 e monitor CGA de 80 colunas x 25 linhas

Nesta época, ferramentas de controle de versão não eram tão comuns, nem monitores de 21 polegadas. Foi então que surgiram alguns paradigmas. Eram consideradas boas práticas de programação usar no máximo 80 colunas por linha de código (limitação causada pelos monitores da época), e incluir informações no cabeçalho do arquivo como @version, @author, @date, @changes etc.

O problema é que para muitas pessoas estes paradigmas perduram até hoje, por herança, por gosto (ou mazoquismo mesmo). Qualquer ferramenta decente de controle de versão pode te trazer, desde sua criação, todo o histórico de alteração de um arquivo. Além de ser mais seguro e confiável. Se eu usar no código-fonte “@author pica-pau”, grande parte das pessoas não irá perceber, porque ninguem lê o cabeçalho do arquivo. Também não existe garantia de que o nome documentado no código-fonte é realmente o do desenvolvedor. Já com uma ferramenta de controle de versão esta garantia existe.

Eu mesmo usava @author nos cabeçalhos uns tempos atrás, mas parei de usar depois que comecei a criticar alguns paradigmas que tinha. É tudo questão de delegar para ferramentas o que pode ser automatizado e buscar novas soluções para os mesmos problemas.

Fábio Miranda@fabiolnm
Não uso por pura falta de hábito – nunca trabalhei em um projeto onde essa prática fosse adotada.
Mas acho interessante, não só o autor, como o email / github tb.

Pode ocorrer de ser necessário dar manutenção em determinado código cuja compreensão não seja trivial, e a possibilidade de contactar o autor, mesmo que remota, deve ser considerada e viabilizada. Não vejo razão para ser contra.

E pra finalizar, os comentários fundamentados de Hanneli Carolina @hannelita – sobre o uso de @author e muito mais:

Bom, vou dar minha opinião sobre comentários no código antes de qualquer coisa…. Também utilizarei algumas metáforas e exemplos reais.

Eu já trabalhei com códigos de sistemas legados – Mainframes e sistemas bem antigos – , envolvendo C e Assembly. Vou contar uma coisa – quando abríamos um código e víamos infinitas linhas de comentário, já sabíamos que vinha coisa ruim pela frente. Tudo bem para aquele tipo de código sempre achei necessário comentar – Há algumas subrotinas do inferno que precisam de explicação. E o cara que fez isso tem idade pra ser meu pai, já faleceu ou se aposentou. Portanto, códigos assim são “legíveis” graças aos comentários deixados para trás. Já peguei código em Assembly sem comentários. E fiquei quase 10 dias só pra entender por cima o que o programa fazia.

Mas atualmente estamos em uma época onde encontramos linguagens extremamente expressivas, como Ruby e Python. E pra ajudar ainda tem uns framewroks tipo Sinatra, incorporando DSLs. Ou seja, hoje é possível escrever códigos que HUMANOS são capazes de ler. (humanos comuns, quis dizer hehehe). Se você escreve códigos em Ruby que humanos não entendem, então sinto muito, meu amigo, vá ler o Clean Code ou aprender a programar de forma limpa. Aliás, práticas de TDD ou BDD, por exemplo, influenciam e praticamente geram um código limpo e legível dadas as etapas que sugerem na construção da aplicação. Por exemplo, o famoso “Vermelho, verde, refatorar” do TDD – O refatorar ocasiona um cógido extremamente mais compreensivo. Construído tal código sólido e bem estruturado, eu questiono – comentários para que? Eles perdem o sentido. Por exemplo, você se depara com a seguinte expressão em Ruby:

unless valor == 0
	puts "Valor diferente de zero!"
end

Bem expressivo, certo? Pra que um comentário então? Uma das coisas que me irrita um pouco é encontrar códigos assim:

public class Pessoa {
	private String nome; //define o nome da pessoa
	private int idade; // define idade da pessoa
}

Ou pior, bem pior que isso:

public class Pessoa {
	private String a; //define o nome da pessoa
}

Ambos os casos eu considero inapropriados. O primeiro por gerer redundância – é ÓBVIO que o atributo "nome" faz menção ao nome da entidade pessoa! O segundo exemplo nos remete a alguém que não fez uso de bom senso de orientaćão a objetos para definir o nome do atributo. O comentário era necessário porque não houve refatoração e uso de um nom esclarecedor ao campo. De qualquer forma, isso é incorreto no meu ponto de vista.

Então quando usar comentários? Costumo usar comentários quando, por exemplo, utilizei algum recurso pouco conhecido da linguagem. Por exemplo, o uso de Fibers no Ruby – poucas pessoas sabem o que são Fibers; coloquei um comentário no meu código extremamente sucinto explicando o que era e onde achar mais informações. Ou se você utilizar alguma magia-negra no código, embebida por metaprogramação, por exemplo, acho que é bom deixar um comentário sucinto do que aquilo quis dizer. Esse tipo de comentário ajuda programadores juniors a adquirir experiência e ajuda até memso os seniors a captar a idéia geral de um método/bloco que possui lógica complexa.
E há alguns casos que comentários podem ajudar a leitura do código fluir e ficar mais agradável. Pra Java, por exemplo, existe uma API – GAG >= Google Annotations Gallery da qual já fui colaboradora. Essas anotações dão emoćão ao código; de vez em quando acho interessante utilziar algumas delas; tornam o coódigo mais expressivo. Novamente, acho que se deve usar sem abusos =)

Sobre o uso do @author – Aí já acho que é uma cosia meio pessoal. Eu não coloco. Saber que sou colaboradora/commiter do projeto já está bom pra mim. A ligação entre eu e o código fonte vai muito mais além que um @author. Claro, tem o lado bom de se colocar; todos que tiverem o fonte saberão o responsável por aquela ciração, e poderão parabenizá-lo, encontrá-lo no Twitter ou no Facebook e coisas do gênero. Ou poderão xingar sua mãe com vontade. Mas acredito que há outras formas de se descobrir e pedir ajuda sobre algum fonte que não são através do @author.

Bom, essa é minha visão geral da coisa! =D

E aí, é contra ou a favor do @author ?

Hélio Costa

Desenvolvedor de software há um tempinho. Interessou-se por Object-Oriented Design e Test-first antes do Eddy Merckx ser removido na organização da UCI Road World Championships.

Sao Paulo, Brazil