Est-il nécessaire d'écrire un commentaire javadoc pour CHAQUE paramètre dans la signature d'une méthode?

L'un des développeurs de mon équipe pense qu'il est nécessaire d'écrire un commentaire javadoc pour CHAQUE paramètre dans 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-documentés. Si vous ne savez pas immédiatement à quoi servent vos paramètres, vous vous trompez probablement. Cependant, je comprends que parfois on ne sait pas à quoi sert un paramètre, donc dans ces cas, oui, vous devez écrire un commentaire javadoc expliquant le paramètre.

Mais je pense qu'il n'est pas nécessaire de le faire pour CHAQUE paramètre. S'il est déjà évident à quoi sert le paramètre, le commentaire javadoc est redondant; vous créez simplement du travail supplémentaire pour vous-même. De plus, vous créez du travail supplémentaire pour quiconque doit maintenir votre code. Les méthodes changent au fil du temps et la conservation des commentaires est presque aussi importante que la maintenance de votre code. Combien de fois avez-vous vu un commentaire comme "X fait Y pour raison Z" seulement pour voir que le commentaire est obsolète, et en fait la méthode ne prend même plus de 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 nuisible que pas de commentaire du tout. Et c'est donc le danger de trop commenter: en créant une documentation inutile, vous '

Cependant, je respecte l'autre développeur de mon équipe et accepte que peut-être il a raison et que je me trompe. C'est pourquoi je vous pose ma question, collègues développeurs: est-il vraiment nécessaire d'écrire un commentaire javadoc pour CHAQUE paramètre? Supposons ici que le code est interne à mon entreprise et ne sera consommé par aucun tiers.

Les annotations Javadoc (et, dans le mot Microsoft, XMLDoc) ne sont pas des commentaires , elles sont de la documentation .

Les commentaires peuvent être aussi clairsemés que vous le souhaitez; en supposant que votre code est lisible à mi-chemin, les commentaires ordinaires ne sont que des panneaux indicateurs pour aider les futurs développeurs à comprendre / maintenir le code qu'ils ont déjà regardé pendant deux heures.

La documentation représente un contrat entre une unité de code et ses appelants. Il fait partie de l'API publique. Supposez toujours que Javadoc / XMLdoc se retrouvera soit dans un fichier d'aide soit dans une fenêtre contextuelle de saisie semi-automatique / intellisense / complétion de code, et sera observé par des personnes qui n'examinent pas les éléments internes de votre code mais souhaitent simplement l' utiliser à des fins de les leurs.

Les noms d'argument / paramètre ne sont jamais explicites. Vous pensez toujours qu'ils le sont lorsque vous avez passé la dernière journée à travailler sur le code, mais essayez d'y revenir après deux semaines de vacances et vous verrez à quel point ils sont vraiment inutiles.

Ne vous méprenez pas - il est important de choisir des noms significatifs pour les variables et les arguments. Mais c'est un problème de code, pas un problème de documentation. Ne prenez pas trop littéralement l'expression «auto-documentation»; c'est-à-dire dans le contexte de la documentation interne (commentaires) et non de la documentation externe (contrats).

Soit tout commenter ou rien du tout (évidemment, tout commenter est un bien meilleur choix). Pensez à quelqu'un qui utilise votre code, soit en examinant votre API directement dans votre fichier source ou dans un fichier doc généré (c'est-à-dire une sortie doxygen). Les incohérences conduisent généralement à la confusion, ce qui conduit à passer du temps à fouiller dans la source pour comprendre pourquoi quelque chose n'a pas été commenté, ce qui conduit à une perte de temps qui aurait pu être évitée si le paramètre venait d'être commenté en premier lieu.

Rappelez-vous: Quelque chose qui a du sens pour vous peut être interprété complètement différemment par quelqu'un d'autre, peu importe à quel point vous pensez que c'est banal (pensez à quelqu'un qui n'est pas aussi fort en anglais en lisant et en essayant de comprendre votre code).

Cela dit, si l'autre développeur souligne l'importance de tout documenter, il faut tout autant mettre l'accent (sinon plus) sur la mise à jour de la documentation. Comme vous l'avez dit, il n'y a pas pire que d'avoir des commentaires obsolètes (tout aussi mauvais, sinon pire que des documents omis).

Commençons par l'hypothèse que les cycles de développement sont la ressource que nous essayons de conserver.

Cela signifie donc que les développeurs ne devraient pas perdre de temps à documenter les paramètres évidents et les valeurs de retour, non?

Eh bien, décomposons-le.

Si nous documentons tout, en supposant que les commentaires marginaux sont vraiment insignifiants et ne nécessitent aucune réflexion ou recherche, le coût est le temps supplémentaire pour réellement taper le commentaire et corriger les fautes de frappe.

Si nous choisissons et choisissons, les coûts sont les suivants:

• Avoir et gagner l'argument avec les autres développeurs de votre équipe qui pensent que tout doit être documenté.
• Pour chaque paramètre, déterminer si cela doit ou non être documenté.
• Plus d'arguments avec votre équipe lorsque quelqu'un a une opinion différente sur la question de savoir si un paramètre aurait dû être documenté.
• Passez du temps à rechercher le code et à rechercher lorsqu'un paramètre jugé explicite ne l'est pas.

Donc, je serais enclin à tout documenter. L'inconvénient est certain, mais il est contenu.

Si vous écrivez Javadoc de toute façon, vous pourriez aussi bien l'écrire complètement, même en incluant les paramètres "évidents". Ils peuvent être évidents pour vous ou l'autre développeur, mais toute personne nouvelle qui le regarde gagnerait à connaître l'intention de chaque paramètre.

En ce qui concerne la maintenance correcte de Javadoc, vous devez utiliser des outils pour votre développement qui vous aident dans cette tâche. Eclipse me vient à l'esprit. Bien sûr, si c'est important, vous devez vous assurer que tout le monde dans l'équipe fait sa part pour maintenir le code, y compris les commentaires.

N'oubliez pas que javadoc peut être rendu visible tout en étant séparé du code, l'exemple principal étant l' API Java elle-même. En n'incluant pas le javadoc pour chaque paramètre d'une méthode, vous déformez la méthode et la façon dont elle pourrait être utilisée.

«nécessaire» est complètement subjectif. Je pense que ce que vous demandez, c'est «dans votre situation, si vous ajoutez un commentaire javadoc». Ne connaissant pas la portée ou le contexte de votre application, comment savoir ce qui vous convient?

Si ce code accessible au public (c.-à-d. Le code destiné aux autres utilisateurs, comme une API), alors oui, documentez chaque paramètre. Ne présumez pas que le lecteur connaît le projet autant que vous. Mais sinon, c'est à vous et à votre équipe de prendre vos propres décisions.