Dans la plupart des équipes, une règle indique que les mots-clés @Author et @Since doivent être utilisés pour toutes les classes documentées, parfois même des méthodes.
Dans une tentative de se concentrer sur ce qui compte, je n'utilise pas ces mots-clés et s'appuie plutôt sur le fait que je peux utiliser le système de gestion de contrôle source pour déterminer qui l'auteur d'une classe est et depuis lorsqu'il existe. < / p>
Je crois que @Author et @Since viennent d'une époque où le contrôle de la version n'était pas encore courant et je pense qu'ils sont plutôt redondants maintenant. Comment pensez-vous de cela? Les projets Java modernes devraient-ils les utiliser?
5 Réponses :
Je sais que nous les avons utilisés, et ils sont vraiment sympas quand il suffit de parcourir le code source. J'ai eu plus d'une situation où le @Since a été très pratique d'avoir là-bas, car il aurait fallu un peu de travail pour déterminer quelle version a été ajoutée (en comparant les dates, etc.).
juste mon expérience cependant. Je pense que le @Author a été moins utile, mais puisque nous pouvons autogénérer les deux pièces de données lors de la création de nouvelles classes, cela ne semble pas être un gaspillage pour simplement laisser le système me le faire.
Je pense que les règles de la documentation ne doivent être appliquées que si vous en avez besoin. Si c'est redondant pour que vous mettiez ceux de Java Docs, ne faites pas d'exécution de la règle. Un cas où cela importerait, c'est si quelqu'un a déjà besoin de voir ces informations et n'a pas accès à votre contrôle de version
Bien pour une chose que la visibilité Javadoc transcende généralement la visibilité de la commande source. Je peux voir les Javadocs pour la bibliothèque de Java 1.1, mais je ne peux pas faire de mes connaissances librement dans l'historique de la version du Soleil à l'autre.
Vous parlez comme si vos Javadocs sont complètement isolés à vous (le développeur) et non distribués aux autres dans le cadre d'une API, etc. Ce n'est pas toujours le cas. Habituellement, des informations Javadocs et VCS servent des objectifs complètement différents.
Pour moi, même si j'ai un accès libre à l'historique de la version d'un fichier, j'aime pouvoir le voir là-bas dans la source, pour la même raison que j'aime les commentaires expliquant un code étrange dans le fichier au lieu d'avoir Pour aller à la description de commettre pour un certain bloc de code. C'est plus rapide.
Certains systèmes de contrôle de la version apportent même des informations de remplissage de l'auteur et autres que vous pouvez réellement bénéficier d'étuis d'utilisation comme celui-ci sans introduire des informations redondantes. Cela doit généralement être explicitement activé pour empêcher la corruption des fichiers où les marqueurs de mots clés ne sont pas destinés à être substitués. C'est la façon dont il fonctionne dans la subversion, par exemple. svnbook.red-bean.com/nightly/ EN / ...
@Archimedix: Je trouve que c'est un sac mélangé. Je préférerais généralement que l'auteur soit plus statique. Sinon, vous entrez dans le scénario où quelqu'un vient de corriger une faute de frappe sur le fichier, et maintenant ils sont l'auteur du fichier. Notre société est autorégidée et je trouve que cela sera moins utile. Je suis d'accord avec Jqno en pensant que la balise @Author elle-même ne fournit pas beaucoup d'avantages.
Oui, c'est vraiment un problème ... Cependant, je ne peux pas penser à aucune autre façon de résoudre ce logiciel de manière satisfaisante ... pour les fichiers non binaires, on pourrait penser à un mot-clé d'auteurs étendu ou à une version paramétrée de celle-ci que Répertorie les auteurs les plus pertinents en fonction de leur contribution dérivé d'une opération de blâme de VCS (généralement très coûteuse et ne sont donc pas vraiment utiles à cet effet dans la pratique). Alors, on dirait que le seul moyen de l'obtenir bien fait est de le faire soi-même! ;-)
Je pense que la balise Je pense aussi qu'il favorise la propriété du code, que je ne pense pas, c'est une bonne chose. N'importe qui devrait être autorisé à changer un fichier. S'il y a une balise @Author , les gens auront tendance à laisser cet auteur faire toutes les modifications au lieu de le faire eux-mêmes et d'apprendre quelque chose dans le processus.
Enfin, comme vous l'avez dit, les mêmes informations, dans beaucoup plus de détails sont disponibles à partir de votre VCS. Tout ce que vous ajoutez dans Javadoc est la duplication. Et la duplication est mauvaise, non?
edit: Autres réponses mentionnez le fait que vous n'ayez peut-être pas accès aux VCS, et dans de tels cas, la balise @Author confond des choses. Tout d'abord, si ce n'est pas mis à jour judicieusement, cela devient faux. En outre, que si vous (n'étant pas l'auteur d'origine) change une demi-classe? Mettez-vous à jour le @Author ? Ajoutez-vous un? Et si vous ne changez que quelques lignes dans la classe?
@Author est utile. Je suis humblement en désaccord. Dans de tels cas, vous traitez probablement une bibliothèque tierce, ou peut-être un artefact d'une autre équipe dans votre entreprise. Si tel est le cas, cela compte-t-il vraiment de savoir qui était l'individu qui a créé une certaine classe? Très probablement, il vous suffit de connaître l'entité qui a créé la bibliothèque et de parler à leur personne de contact.
Je ne suis pas en désaccord avec l'évaluation de la balise @Author du tout - +1
La duplication n'est valable que pour la redondance, comme dans la correction des erreurs.
Totalement d'accord avec l'inutilité de la balise @Author . La balise @Since peut être pratique avec la documentation de la bibliothèque publique cependant. "Pourquoi ne puis-je pas utiliser cela? Ah, il a été ajouté en 4.9, mais j'ai 4,2 ..."
non. Le public des pages Javadoc peut ne pas avoir accès à votre contrôle source, de sorte que ces informations sont pertinentes.
Le @Since est important car la documentation peut être consultée pour les anciennes versions du logiciel. Lorsque vous pouvez voir quand une fonctionnalité vous a été introduite, vous savez 1) qu'il est indisponible pour vous et 2) qu'il existe une bonne raison de la mise à niveau.
Vous pourriez toutefois utiliser une adresse électronique pour l'auteur de contacter votre équipe pour la balise @Author.
Accepter avec l'utilité de @since , mais oui ... qui se soucie de ce qu'Is individu a écrit une classe ou une méthode particulière?