La documentation api et les & # 8220; limites de valeur & # 8221 ;: correspondent-elles?

Question

Voyez-vous souvent dans la documentation de l'API (comme dans "javadoc des fonctions publiques", par exemple) la description de "valeur limite"? ainsi que la documentation classique?

Remarque: je ne parle pas de commentaires dans le code

Par "limites de valeur", je veux dire:

• un paramètre peut-il prendre en charge une valeur null (ou une chaîne vide, ou ...)?
• une 'valeur de retour' peut-elle être nulle ou garantie de ne jamais l'être (ou peut-elle être "vide", ou ...)?

Exemple:

Ce que je vois souvent (sans avoir accès au code source) est:

/**
 * Get all readers name for this current Report. <br />
 * <b>Warning</b>The Report must have been published first.
 * @param aReaderNameRegexp filter in order to return only reader matching the regexp
 * @return array of reader names
 */
 String[] getReaderNames(final String aReaderNameRegexp);

Ce que je veux voir serait:

/**
 * Get all readers name for this current Report. <br />
 * <b>Warning</b>The Report must have been published first.
 * @param aReaderNameRegexp filter in order to return only reader matching the regexp 
 * (can be null or empty)
 * @return array of reader names 
 * (null if Report has not yet been published, 
 *  empty array if no reader match criteria, 
 *  reader names array matching regexp, or all readers if regexp is null or empty)
 */
 String[] getReaderNames(final String aReaderNameRegexp);

Mon point est le suivant:

Lorsque j'utilise une bibliothèque avec une fonction getReaderNames (), je n'ai souvent même pas besoin de lire la documentation de l'API pour deviner ce qu'elle fait. Mais je dois être sûr comment l’utiliser .

Mon seul souci lorsque je souhaite utiliser cette fonction est la suivante: à quoi dois-je m'attendre en termes de paramètres et de valeurs de retour? C’est tout ce que je dois savoir pour configurer en toute sécurité mes paramètres et tester la valeur de retour en toute sécurité. Pourtant, je ne vois presque jamais ce genre d’informations dans la documentation de l’API ...

Modifier:

Cela peut influencer ou non l'utilisation de exceptions cochées ou non cochées .

Qu'en penses-tu? limites de valeur et API, sont-ils liés ou non?

Answer 1

Je pense qu'ils peuvent appartenir ensemble mais qu'ils ne pas nécessairement appartenir ensemble. Dans votre scénario, il semble logique que les limites soient documentées de manière à ce qu'elles apparaissent dans la documentation de l'API générée et dans intellisense (si la langue / l'EDI le prend en charge).

Je pense que cela dépend également de la langue. Par exemple, Ada a un type de données natif qui est un "entier restreint", dans lequel vous définissez une variable entière et indiquez explicitement qu'elle sera seulement (et toujours) dans une certaine plage numérique. Dans ce cas, le type de données lui-même indique la restriction. Il devrait toujours être visible et accessible à travers la documentation de l'API et intellisense, mais ce ne serait pas quelque chose qu'un développeur doit spécifier dans les commentaires.

Toutefois, les langages tels que Java et C # n’ont pas ce type d’entier restreint, le développeur devrait donc le spécifier dans les commentaires s’il s’agissait d’informations devant faire partie de la documentation publique.

Answer 2

Je pense que ces types de conditions aux limites appartiennent très certainement à l'API. Cependant, j'irais (et le ferais souvent) un peu plus loin et indiquerais ce que signifient ces valeurs nulles. Soit j'indique qu'il va déclencher une exception, soit j'explique quels sont les résultats attendus lorsque la valeur limite est transmise.

Il est difficile de se rappeler de toujours le faire, mais c’est une bonne chose pour les utilisateurs de votre classe. Il est également difficile de le maintenir si le contrat de la méthode présente des modifications (comme les valeurs null sont modifiées pour ne pas être autorisées) ... vous devez également faire preuve de diligence pour mettre à jour la documentation lorsque vous modifiez la sémantique de la méthode.

Answer 3

Question 1

  

Voyez-vous souvent dans la documentation de l'API (comme dans "javadoc des fonctions publiques", par exemple) la description de "valeur limite"? ainsi que la documentation classique?

Presque jamais.

Question 2

  

Mon seul souci lorsque je souhaite utiliser cette fonction est la suivante: à quoi dois-je m'attendre en termes de paramètres et de valeurs de retour? C’est tout ce que je dois savoir pour configurer en toute sécurité mes paramètres et tester la valeur de retour en toute sécurité. Pourtant, je ne vois presque jamais ce genre d’informations dans la documentation de l’API ...

Si j'utilisais une fonction pas correctement, je m'attendrais à une RuntimeException renvoyée par la méthode ou à un RuntimeException dans une autre partie (parfois très éloignée) du programme.

Des commentaires tels que @param un filtre aReaderNameRegexp afin de ... (peut être nul ou vide) me semblent un moyen de mettre en œuvre Conception par contrat dans une langue humaine à l'intérieur de Javadoc .

L'utilisation de Javadoc pour appliquer la conception par contrat a été utilisée par iContract , qui est maintenant ressuscité dans JcontractS , qui vous permet de spécifier des invariants, des conditions préalables et des conditions postconditions , de manière plus formalisée que le langage de l'être humain.

Question 3

  

Cela peut influer sur l'utilisation ou non des exceptions cochées ou non.   Qu'est-ce que tu penses ? limites de valeur et API, sont-ils liés ou non?

Le langage Java n’ayant pas de fonctionnalité de conception par contrat, vous pouvez être tenté d’utiliser Execption , mais je suis d’accord avec vous sur le fait que vous devez être au courant de Lorsque vous choisissez les exceptions cochées et non cochées . Vous pouvez probablement utiliser des IllegalArgumentException , IllegalStateException non cochés, ou des tests unitaires, mais le principal problème est de savoir comment communiquer à d'autres programmeurs que ce code concerne Design By Contract et doit être considéré comme un contrat avant de le modifier trop légèrement.

Answer 4

Je pense qu'ils le font et ont toujours placé les commentaires dans les fichiers d'en-tête (c ++) les uns après les autres.

Outre les commentaires d'entrée / sortie / retour valides, je signale également les exceptions susceptibles d'être levées par la fonction (étant donné que je souhaite souvent utiliser la valeur de retour pour ... renvoyer une valeur, je préfère les exceptions à codes d'erreur)

//File:
// Should be a path to the teexture file to load, if it is not a full path (eg "c:\example.png") it will attempt to find the file usign the paths provided by the DataSearchPath list
//Return: The pointer to a Texture instance is returned, in the event of an error, an exception is thrown. When you are finished with the texture you chould call the Free() method.
//Exceptions:
//except::FileNotFound
//except::InvalidFile
//except::InvalidParams
//except::CreationFailed
Texture *GetTexture(const std::string &File);

Answer 5

@Fire Lancer: C'est ça! J'ai oublié l'exception, mais j'aimerais qu'ils soient mentionnés, en particulier l'exception non vérifiée "d'exécution" que cette méthode publique pourrait générer

@Mike Stone:

  

vous devez également faire preuve de diligence pour mettre à jour la documentation lorsque vous modifiez la sémantique de la méthode.

Mmmm J'espère bien que la documentation de l'API publique est à tout le moins mise à jour chaque fois qu'un changement - qui affecte le contrat de la fonction - a lieu. Sinon, ces documentations d'API pourraient être abandonnées.

Pour ajouter de la nourriture à vos pensées (et suivre @Scott Dorman), je viens de tomber sur l'avenir des annotations java7

Qu'est-ce que cela signifie? Certaines "conditions aux limites", plutôt que de figurer dans la documentation, devraient être améliorées dans l'API elle-même et automatiquement utilisées au moment de la compilation, avec le code généré "assert" approprié.

Ainsi, si un '@CheckForNull' se trouve dans l'API, le rédacteur de la fonction risque de ne pas le documenter! Et si le changement sémantique change, son API reflétera ce changement (comme 'plus de @CheckForNull' par exemple)

Ce type d’approche suggère que la documentation, pour les "conditions aux limites", est un bonus supplémentaire et non une pratique obligatoire.

Cependant, cela ne couvre pas les valeurs spéciales de l'objet de retour d'une fonction. Pour cela, une documentation complète est toujours nécessaire.