@Author ?

En discutant de l’intérêt de l’usage de la javadoc, question primordiale il faut l’avouer, nous avons dérivé sur un sujet encore plus intéressant : l’utilité de la balise @Author dans la javadoc :p Meme si sur Twitter, le @Author est considéré comme inutile, quasiment à l’unanimité, ce n’est pas le cas partout.

Le pour

– Je suis auteur de mon code, je l’assume et je l’écris de manière professionnelle en pensant à ceux qui vont me lire. C’est une idée que partage Robert C. Martin.

The @author field of a Javadoc tells us who we are. We are authors. And one thing about authors is that they have readers. Indeed, authors are responsible for communicating well with their readers. The next time you write a line of code, remember you are an author, writing for readers who will judge your effort.

– Surtout dans l’open-source, cela permet de laisser une trace de son investissement. Voir de se faire un nom.
– Il peut contenir l’adresse d’une mailing-list, ce qui permet, lors d’une question sur une classe de contacter directement les personnes responsables.

Le contre

– DRY : don’t repeat yourself : l’information est déja présente dans le SCM (git, svn ..).
– Le code appartient à tous : le @author doit donc etre collectif.
– Si il ne contient que l’auteur initial, celui-ci ne vaut pas plus que les autres.
– évite la sacralisation d’un unique développeur
– Pose le problème de savoir quand on doit se rajouter dans la balise @author.

Je laisse à Emmanuel Bernard le tweet de la fin :

Merci à ‏Sébastien PRUNIER ‏ @sebprunier, Pierre TEMPLIER ‏ @ptemplier, Emmanuel LECHARNY, François Sarradin ‏ @fsarradin, Guillaume LOURS ‏ @guillaumelours, Jean-Laurent Morlhon ‏ @morlhon, Arnaud Héritier ‏ @aheritier , Sébastien Deleuze ‏ @sdeleuze , Yannick AMEUR ‏ @yannickameur , Robin Komiwes ‏ @robinkomiwes , Jollivet Christophe ‏ @jollivetc , Jérémy Sevellec ‏ @jsevellec, Julien Jakubowski ‏ @jak78 , Nicolas De loof ‏ @ndeloof, Nicolas François ‏ @nicofrancois , Francois Marot ‏ @FrancoisMarot , Jean Helou ‏ @jeanhelou, Benoît Dissert ‏ @bdissert , Olivier Jaquemet ‏ @OlivierJaquemet , Aline Paponaud ‏ @bootis , Benoît Dissert ‏ @bdissert , Nicolas Delsaux ‏ @riduidel et aux autres …

3 Responses to “@Author ?”

  1. SRG dit :

    Pour moi la règle est simple : sur un projet personnel (par ex. publié sur mon github), j’ai plutôt tendance à le mettre.
    Sur des projets collaboratifs ou réalisés en équipe (cas très courant en entreprise), je trouve en effet qu’il devient à l’inverse déplacé, parce que rares sont les classes à ne pas être touchées / modifiées par plusieurs personnes au fil du temps (comme évoqué, la balise @author perd alors toute signification).
    De toutes façons le « qui a écrit ce code » est clairement remplacé aujourd’hui par les mécanismes de visualisation de révisions d’Eclipse (« Show Annotations »).

  2. Dans le cadre « Open Source », cela permet également de citer les personnes qui ont apporté un patch, une fonctionnalité sans avoir accès au SCM en écriture, et qui auraient proposés le patch via une archive soumise via email/issue tracking.

  3. Jean-Baptiste dit :

    @SRG Quand bien même tu retouches entièrement un code, tu en es l’auteur et ceux qui ont écrit le code que tu as « effacé » restent auteurs aussi car sans leurs code, le tiens n’aurait pas été ce qu’il est.

    On efface pas un @author, on en ajoute. Le développement est itératif, il est co-écrit par des co-auteurs.

Leave a Reply