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.