Documenter la logique dans javadoc

Question

J'ai une question sur l'endroit où documenter la logique dans javadocs. Par exemple, j'ai la signature de la méthode suivante dans une interface:

public int getTotalAssociationsAsParent(Long id, Long type); 

La méthode renvoie les associations où l'ID donné est le parent et l'association est de type « type ». ID est requis, mais si le type transmis est NULL, alors je retournerai TOUTES les associations où l'ID est le parent.

Ma question est où devrait-on documenter ce type de logique? J'hésite à le mettre dans le javadoc de l'interface car cela contraint toutes les classes d'implémentation à adhérer à cette logique. Peut-être que dans le futur, j'aurai une classe Impl qui lance une exception IllegalArgumentException si le type est NULL.

Cependant, si je le place dans un non-javadoc dans la classe Impl, alors les consommateurs de cette méthode ne connaîtront pas le comportement de la méthode avec un type NULL.

Answer 1

Ce que vous décrivez est le contrat d'interface de la méthode, donc il appartient en effet au Javadoc. Les clients de l'interface doivent connaître le contrat exact que cette interface remplit. Si une classe dérivée implémente la méthode différemment, elle rompt effectivement le contrat et rompt ainsi le Liskov Substitution Principle.

Toutefois, si vous pensez qu'il ya vraiment place pour différentes implémentations de cette méthode, vous avez quelques choix:

• Repensez votre conception - peut-être ces mises en œuvre ne doivent pas être dans les sous-classes de la même interface, ou peut-être vous avez besoin de deux méthodes distinctes dans cette interface
• définir le contrat sans serrer pour permettre une variance de mise en œuvre (mais seulement si elle est logique du point de vue des clients!)

Answer 2

vous devez décrire ce qu'il re se tourner vers le client dans quel cas. Le client n'a pas besoin de savoir comment vous le faites pour le renvoyer mais il devrait savoir avec quelques types d'entrée, une sortie spéciale sera retournée.

À l'avenir, si vous voulez lancer une exception, vous devez changer votre javadoc de sorte que l'appelant peut savoir qu'il doit gérer une exception

Answer 3

En général, vous mettez cela sur l'interface, les définit l'interface le comportement des implémentations. Cependant, il n'y a pas de règle stricte ici, si une implémentation particulière se comporte différemment, vous pouvez également mettre cette différence sur le commentaire de mise en œuvre. Ceci est très similaire à la façon dont la Java Standard Library fait les choses dans leur JavaDoc.

Tenir compte, par exemple, ArrayList:

http://java.sun.com/javase/6/docs/api/java/util/ArrayList.html

a removeAll, qui est défini dans la liste et mis en œuvre AbstractCollection

http://java.sun.com/javase/6/docs/api/java/util/List.html#removeAll(java.util.Collection)

http://java.sun.com/javase/6/docs/api/java/util/AbstractCollection.html#removeAll(java.util.Collection)

La liste définit la classe ce qu'il fait, la classe AbstractCollection définit son comportement particulier.Les documents sont un outil, alors utilisez-les comme bon vous semble, la partie la plus importante de cet outil est qu'ils sont tenus au courant - donc trop de documentation peut causer des maux de tête plus tard, sous documentation aussi! En général, essayez également de garder le code que vous écrivez dans chaque méthode court et concis et aussi libre des effets secondaires que possible, de cette façon vous êtes capable de lire le code et comprendre ce que cela signifie de faire sans trop dépendre de la documentation environnante .

Answer 4

est parfait pour Javadoc:

/** 
* The method returns associations where the given ID is the parent and the association is of type 'type'. <br> 
* ID is required, but if type passed in is NULL, then I will return ALL associations where the ID is the parent.<br> 
*<br> 
* Subclasses may throw an IllegalArgumentException if type is NULL.<br> 
* @param id Parent identifier 
* @param type the type of association 
* @return the Association or null if type is null 
*/ 
public int getTotalAssociationsAsParent(Long id, Long type) 

Je souhaite avoir eu ce genre de doc dans le passé moi-même.

je reçois habituellement:

/** 
* get the total associations as parent 
* @param id the id 
* @type the type 
*/ 
public int getTotalAssociationsAsParent(Long id, Long type); 

Ce qui est pas utile.