web-dev-qa-db-fra.com

JavaDoc pour les méthodes privées / protégées?

Dois-je écrire JavaDoc pour les méthodes private ou protected? Et qu'en est-il des variables privées?

Je vois des exemples de classe sur mon Java livre et les variables private sont JavaDoc'ed. Je ne peux donc pas comprendre si c'est une bonne pratique de JavaDoc le - privé (ou protégé) méthodes.

javajavadocprivateprotected
45
smartmouse

Oui, vous devez écrire JavaDoc pour les méthodes privées, et même quand ce n'est que pour vous. Dans 3 ans où vous devrez changer le code, vous serez heureux de l'avoir documenté.

Si vous quittez l'entreprise ou devez travailler sur un autre projet, vos collègues seront heureux d'avoir un code documenté. Le code non documenté a une valeur beaucoup plus faible.

Et regardez comment les vrais professionnels le font. Voici un extrait du code source de la classe ArrayList par Sun Microsystems :

 /**
  * The array buffer into which the elements of the ArrayList are stored.
  * The capacity of the ArrayList is the length of this array buffer.
  */
  private transient Object[] elementData;
51
AlexWien

La première question que vous devez vous poser est "pourquoi écrire JavaDocs?" À qui sont-ils utiles? Qui vous a demandé de les écrire?

Très probablement, quelqu'un (employeur/professeur) vous a demandé de documenter certaines de vos méthodes. C'est généralement une bonne chose, mais cela a un coût: un entretien supplémentaire.

Si vous avez une version accessible au public de vos documents (par exemple, si vous les générez et les publiez en ligne pour les utilisateurs finaux), il est logique de documenter tout que vos utilisateurs finaux devront Cela inclut toutes les classes et méthodes publiques.

Et pour vous et les autres développeurs?

Mon opinion est que vous ne devez pas utiliser javadocs sur les méthodes et classes internes et privées. La raison principale est que les javadocs profitent principalement aux personnes qui consomment, et non maintiennent, votre code.

En revanche, vous devez conserver des notes et des commentaires sur votre propre code, qui est souvent interne. Dans ce cas, je suggère des commentaires normaux (par exemple. //) au lieu; c'est moins d'entretien, et souvent, tout aussi clair, avec beaucoup moins de frappe.

D'un autre côté, si une méthode devient publique, il peut être utile de convertir ces commentaires en véritables javadocs. Les Javadocs ont l'avantage de vous forcer à penser (et à documenter) chaque paramètre, exception et valeur de retour.

Le compromis est à vous.

38
ashes999

Non, vous ne devriez pas écrire javadoc pour les méthodes privées. Les utilisateurs finaux n'ont pas accès aux champs ou méthodes privés, il est donc inutile de leur fournir du javadoc. Les champs et méthodes privés sont réservés au développeur. Si vous en avez vraiment besoin, n'hésitez pas à écrire des commentaires pour une logique non évidente. Vous devriez probablement écrire javadoc pour les méthodes protected car ces méthodes sont parfois remplacées et il est utile de fournir à l'utilisateur des informations sur ce que la méthode fait ou doit faire.

6
Josh M

Vous entendez souvent la recommandation générale selon laquelle, dans le meilleur des cas, les commentaires ne doivent tout simplement pas être nécessaires du tout. Mais concernant JavaDoc, ils jouent un rôle important non seulement pour le développeur, mais aussi pour l'utilisateur de la bibliothèque.

De plus, écrire des commentaires JavaDoc peut être plus utile pour vous (en particulier pour un débutant) que pour quiconque: lorsque vous avez du mal à décrire ce qu'est une variable ou ce qu'une méthode fait avec un seul /** One-line-JavaDoc comment */, Alors vous 'repenserai automatiquement ce que vous y avez fait.

Lors de la génération de JavaDocs, vous pouvez choisir de les générer uniquement pour les parties public et protected de l'API, ou également pour les éléments par défaut ou private.

Cependant, vous devriez dans tous les cas documenter les méthodes protected: Est-ce que quelqu'un qui étend la classe uniquement appel cette méthode, ou est-il également autorisé à remplacer cette méthode? Si oui, y a-t-il des conditions préalables et postconditions qu'il devrait connaître? Doit-il appeler super.theMethod() dans la version surchargée? (BTW: s'il n'est pas autorisé à remplacer la méthode, alors elle devrait être final, mais documentée de toute façon)

BTW: Je commente personnellement tout, mais sachez que la plupart des gens pensent que ce n'est pas nécessaire ou même un mauvais style, surtout pour les choses "triviales"

/**
 * The number of elements in this set
 */
private final int numberOfElements;

Je pense que cela ne nuit pas, mais aide dans de nombreux cas. Peut-être, en ce qui concerne private pièces, c'est juste une question de goût.

5
Marco13

Vous n'avez rien à javadocer, mais c'est très utile. Plus de javadocs ne sont jamais une mauvaise chose.

Selon votre question, si vous utilisez le compilateur de documentation javadoc, les javadocs seront compilés pour les méthodes protégées, mais pas pour les méthodes privées. Il n'y a cependant aucune raison pour qu'ils ne puissent pas être utilisés comme commentaires de code.

3
Peter Bratton