Est-il nécessaire d'écrire un commentaire Javadoc pour chaque paramètre de la signature d'une méthode?
L'un des Devs de mon équipe estime qu'il est nécessaire d'écrire un commentaire Javadoc pour chaque paramètre de la signature d'une méthode. Je ne pense pas que cela soit nécessaire et, en fait, je pense que cela peut même être nocif.
Tout d'abord, je pense que les noms de paramètres doivent être descriptifs et auto-documentants. Si ce n'est pas immédiatement évident, quels sont vos paramètres, vous le faites probablement mal. Cependant, je comprends que parfois, il est difficile de savoir quel paramètre est pour, donc dans ces cas, vous devriez écrire un commentaire Javadoc expliquant le paramètre.
Mais je pense qu'il est inutile de le faire pour chaque paramètre. Si c'est déjà évident, quel est le paramètre, le commentaire Javadoc est redondant; Vous créez un travail supplémentaire pour vous-même. En outre, vous créez un travail supplémentaire pour quiconque doit conserver votre code. Les méthodes changent au fil du temps et le maintien des commentaires est presque aussi important que de maintenir votre code. Combien de fois avez-vous vu un commentaire comme "x fait y pour z de raison" seulement pour voir que le commentaire est obsolète et, en fait, la méthode ne prend même pas x paramètre x? Cela arrive tout le temps, car les gens oublient de mettre à jour les commentaires. Je dirais qu'un commentaire trompeur est plus néfaste qu'aucun commentaire du tout. Et est donc le danger de sur-commentaire: en créant une documentation inutile, vous rendez plus de travail pour vous-même et tout le monde, vous n'ayez aide personne à comprendre votre code et que vous augmentez la probabilité que le code ait disparu -des commentaires de date à un moment donné à l'avenir.
Cependant, je respecte l'autre développeur de mon équipe et accepte que peut-être qu'il a raison et je me trompe. C'est pourquoi je vous pose ma question, d'autres développeurs: est-il nécessaire d'écrire un commentaire Javadoc pour chaque paramètre? Supposons ici que le code est interne à ma société et ne sera consommé par aucune partie extérieure.
Javadoc (et, dans les annotations Microsoft Word, XMLDOC) ne sont pas Commentaires, ils sont Documentation.
Commentaires Peut être aussi clairsemé que vous le souhaitez; En supposant que votre code soit lisible à mi-chemin, les commentaires ordinaires sont simplement des panneaux de signalisation pour aider les futurs développeurs à comprendre/à maintenir le code qu'ils regardaient déjà deux heures.
Le Documentation représente A contrat entre une unité de code et ses appelants. Cela fait partie de l'API publique. Supposons toujours que Javadoc/XMLDOC se retrouvera dans un fichier d'aide ou dans une fenêtre contextuelle autocomplete/Intellisse/Code/Code, et être observée par des personnes qui sont non Examinant les internes de votre code mais simplement le souhait to Utilisez cela pour un certain but propre.
Les noms d'arguments/paramètres sont jamais Auto-explicite. Vous avez toujours pense Ils sont lorsque vous avez passé la journée passée à travailler sur le code, mais essayez de revenir après des vacances de 2 semaines et vous verrez à quel point ils sont inutiles .
Ne me comprenez pas mal - il est important de choisir des noms significatifs pour les variables et les arguments. Mais c'est une préoccupation de code, pas une préoccupation de la documentation. Ne prenez pas la phrase "auto-documentant" trop littéralement; Cela est signifié dans le contexte de interne Documentation (commentaires), pas externe Documentation (contrats).
Soit tout ce que vous commencez à commenter (évidemment, tout ce que tout est un bien meilleur choix). Pensez à une personne à l'aide de votre code, soit en passant révisé directement votre API dans votre fichier source, soit dans un fichier DOC généré (I.e. DOXYGEN SORTIE). Les incohérences conduisent généralement à la confusion, ce qui entraîne du temps passé à creuser à la source pour comprendre pourquoi Quelque chose n'a pas été commenté, ce qui conduit à un temps perdu qui aurait pu être évité si le paramètre a été commenté dans le premier endroit.
N'oubliez pas que quelque chose qui a du sens pour vous peut être interprété complètement différemment par quelqu'un d'autre, peu importe la façon dont vous pensez que vous pensez que c'est (pensez à quelqu'un qui n'est pas aussi fort en anglais en lisant et essayant de comprendre votre code).
Ayant dit tout cela, si l'autre développeur souligne l'importance de tout documenter, alors tout aussi d'emphase (sinon plus) doit être mis en conserver la documentation à jour. Comme vous l'avez dit, il n'y a pas beaucoup de pire que d'avoir des commentaires hors datés (tout comme mauvais, sinon pire que les docs omis).
Commençons par l'hypothèse que les cycles de développeurs sont la ressource que nous essayons de conserver.
Cela signifie donc que les Devs ne devraient pas perdre de temps à documenter les paramètres évidents et aux valeurs de retour, non?
Eh bien, cassons-le.
Si nous documentons tout, en supposant que les commentaires marginaux soient vraiment triviaux et ne nécessitent aucune pensée ni recherche, le coût est à l'heure ajoutée pour saisir réellement le commentaire et fixer des fautes de frappe.
Si nous choisissons et choisissons, les coûts sont:
- Avoir et gagner l'argument avec les autres développeurs de votre équipe qui pensent que tout devrait être documenté.
- Pour chaque paramètre, déterminer si cela devrait ou ne doit pas être documenté.
- Plus d'arguments avec votre équipe lorsque quelqu'un a un avis différent sur si un paramètre aurait dû être documenté.
- Dès que vous passez à la recherche du code et de rechercher lorsqu'un paramètre qui a été jugé explicatif ne doit pas l'être.
Donc, je serais enclin à tout documenter. L'inconvénient est défini, mais est contenu.
Si vous écrivez de toute façon Javadoc, vous pourriez aussi bien l'écrire complètement, même y compris les paramètres "évidents". Ils peuvent être évidents pour vous ou l'autre développeur, mais tout le monde qui envisage qu'elle envisageait de connaître l'intention de chaque paramètre.
En ce qui concerne le maintien de Javadoc correctement, vous devez utiliser des outils pour votre développement qui vous aident avec cela. Eclipse vient à l'esprit. Bien sûr, si c'est important, vous devez vous assurer que tout le monde de l'équipe fait sa part de maintenir le code, y compris des commentaires.
N'oubliez pas que Javadoc peut être visible lorsqu'il est séparé du code, un exemple de choix étant le API Java lui-même. En n'incluant pas le Javadoc pour chaque paramètre dans une méthode, vous devez déformer la méthode et la manière dont cela pourrait être utilisé.