Javadoc @author tag bonnes pratiques
Je m'interroge sur les meilleures pratiques lors de la création de Javadocs. J'ai un projet avec plusieurs fichiers. Le code a été créé par de nombreux développeurs. Chaque fichier a une annotation @author, il est donc évident qui a créé une classe particulière.
Mais lorsqu'un autre développeur ajoute un nouveau code à un fichier, le modifie, etc., comment doit-il informer le reste de l'équipe qu'il a créé une nouvelle fonction ou modifié le code existant? En d'autres termes, comment devrions-nous "garder les Javadocs compatibles avec la réalité"? ;)
- Ajouter son nom à la balise
@authorexistante? Ensuite, il est plus facile d'identifier à qui demander en cas de doute. - Ajoutez une balise
@authorà chaque nouvelle méthode, classe interne, etc.?
Bien sûr, puisque nous utilisons SVN, il est facile de déterminer qui a fait quoi, mais, pour que tout soit clair, nous devons également prendre en compte cette information Javadoc.
Quelle est la meilleure façon d'utiliser ces balises @author?
Je dirais que, dans la plupart des cas, @author est un bruit indésirable. L'utilisateur de votre API ne doit pas - et probablement ne le veut pas - se soucier ou vouloir savoir qui a écrit quelles parties.
Et, comme vous l'avez déjà indiqué, SVN détient déjà ces informations d'une manière beaucoup plus autorisée que le code. Donc, si j'étais membre de l'équipe, je préférerais toujours le journal de SVN et ignorerais le @author. Je parie que le code ne sera plus en phase avec la réalité, quelle que soit la politique que vous avez adoptée. Suivant le principe «Ne te répète pas», pourquoi conserver cette information à deux endroits?
Si, toutefois, il existe une raison bureaucratique ou politique pour que ces informations DOIVENT être incluses dans le code, avez-vous envisagé de mettre à jour automatiquement la balise @author dans le code lors de l'enregistrement? Vous pourriez probablement y parvenir avec un hook SVN. Vous pouvez par exemple répertorier tous les développeurs qui ont modifié un fichier dans l'ordre de leur modification. ou qui l'a le plus changé; ou peu importe. Ou, si le @author est obligatoire dans le code (source) que vous transmettez au monde extérieur, vous pouvez envisager d'ajouter le @author automatiquement dans le cadre de la création de la version (je suppose que vous pourriez extraire ces informations de SVN).
En ce qui concerne l'ajout de plusieurs balises @author de niveau de classe (ou d'un autre commentaire), je dirais que vous accumulez beaucoup de bruits inutiles. (Encore une fois, vous avez SVN.)
D'après mon expérience, il est beaucoup plus utile d'identifier un changement historique (par exemple, un changement de ligne de code ou une méthode), puis de déterminer le jeu de modifications concerné (et le ticket de suivi). Ensuite, vous avez le contexte complet pour le changement: vous avez le ticket, le jeu de modifications, vous pouvez trouver d’autres jeux de modifications sur le même ticket ou à peu près au même moment, vous pouvez rechercher des tickets associés et voir TOUTES les modifications apportées. formé cette unité de travail. Vous n'obtiendrez jamais cela à partir d'annotations ou de commentaires dans le code.
Vous voudrez peut-être envisager pourquoi vous voulez des balises d'auteur dans la source. La Fondation Apache n'est pas et je suis d'accord.
http://www.theinquirer.net/inquirer/news/1037207/Apache-enforces-the-removal-of-author-tags
À ma connaissance, il s'agit d'une méthode de travail culte pour les cargaisons à partir du moment où les sources ont été imprimées sur du papier. Avec les systèmes de contrôle de version modernes, ces informations, entre autres, peuvent néanmoins être trouvées dans l'historique.
Vous pouvez avoir plus d'une balise @author. Au cas où vous apporteriez de gros changements à une classe, ajoutez simplement une nouvelle balise @author avec votre propre nom. Il n'est pas nécessaire de marquer les modifications que vous avez apportées ou de mettre votre nom autour des modifications, car l'historique de révision devrait pouvoir l'afficher clairement.
Dans les projets vraiment grands et longs avec beaucoup de développeurs, il est utile de savoir qu'il est responsable d'un code donné, qui peut vous fournir des informations supplémentaires, etc. Dans ce cas, il serait pratique d’avoir une telle information dans le fichier en utilisant la balise @author. Ne pas indiquer qui a créé le fichier ou qui a apporté des contributions importantes, mais qui est une personne de contact pour ce code. Il peut s’agir de personnes très différentes, car l’auteur original peut être déjà sur un projet différent ou avoir quitté la société il ya des années.
Je pense que sur un projet de grande envergure, cette approche peut être pratique, mais il y a une mise en garde. Il est très difficile de conserver les informations relatives à l'auteur de chaque fichier car il existe une quantité énorme de fichiers et que tôt ou tard, cela échouera. De plus en plus de fichiers contiennent des informations obsolètes et les développeurs ne feront plus confiance à @author en tant que source d'informations et l'ignoreront simplement.
La solution, qui peut fonctionner, consiste à ne pas conserver @author sur chaque fichier, mais uniquement par module (packages de haut niveau). Javadoc a une fonctionnalité dans laquelle vous pouvez documenter non seulement des fichiers mais des paquets entiers ( Voir cette question pour plus de détails ).
Il s’agit toutefois d’un cas particulier et, tant que votre projet n’est pas si grand ou si ancien, je vous recommande de ne pas utiliser les informations sur l’auteur.
Je suis tout à fait d'accord pour dire que c'est inutile et que vous ne devriez probablement pas l'ajouter. Cependant, je l’ajoute quand même, c’est comme ajouter une signature à une peinture, ou l’ajouter à un timbre sur un morceau de métal d’un ordinateur a aidé à la conception . Vous avez écrit ce morceau de code et ajouter votre nom montre que vous en êtes fier et que vous avez confiance en sa qualité, même s'il ne fait rien d'autre. Même si cela change à l'avenir, vous avez jeté les bases de tout ce qui a été construit, et si vous le réécrivez complètement, l'étiquette peut être modifiée, supprimée ou développée. Je conviens que cela est redondant grâce au contrôle de version, mais avoir votre nom dans le contrôle de version n’est pas aussi satisfaisant. Si quelqu'un ajoute simplement une "finale" ou formate le code, son nom sera dans le contrôle de version, même s'il a à peine contribué. Je conviens également que c'est du bruit, en ce sens que cela n'ajoute rien au code, mais est-il vraiment légèrement gênant? Je ne pense pas. Si vous êtes raisonnable à ce sujet, je pense que cela peut rendre un projet "plus convivial", si cela a du sens.
C'est très pratique d'avoir la balise @author et d'avoir plusieurs auteurs. Même la documentation d'Oracle indique qu'il est judicieux de placer @author en tête de liste afin de reconnaître les auteurs qui ont fait le travail et de repérer les éléments qui pourraient être utiles au cours du processus de développement. S'il existe plusieurs auteurs, ils peuvent être répertoriés dans l'ordre dans lequel ils ont contribué à un fichier/classe Java particulier. Oui, il existe des plugins et avec la structure git, vous pouvez vérifier que le nom de l'auteur traîne dans le code, mais cette idée sera controversée. Parce que, parfois, plusieurs auteurs modifient la même ligne de code et peuvent ne pas montrer à deux auteurs la même ligne de code. J'ai activé le plugin, il n'affiche jamais le nom de 2 auteurs pour éditer la même ligne de code. Avec les grandes entreprises, il est pratique de mettre en place cette pratique.
Si c'est le code de la société, je ne ferais pas cela: nous avons VCS. Au lieu de cela, s'il s'agit d'un article de blog ou d'extraits de code de mon dépôt personnel, j'ajouterais fièrement ceci et j'espère qu'un gars du copier-coller trouvera mon code utile et accidentellement, copiez mon nom également :)
Juste mon type d'humour, je suppose.