Comment écrire des docstrings significatifs?

StackOverflow https://stackoverflow.com/questions/601900

  •  03-07-2019
  •  | 
  •  

Question

Qu'est-ce qui, à votre avis, est une docstring utile? Qu'espérez-vous y être décrit?

Par exemple, considérons le __ init __ :

de cette classe Python 
def __init__(self, name, value, displayName=None, matchingRule="strict"):
    """
    name - field name
    value - field value
    displayName - nice display name, if empty will be set to field name
    matchingRule - I have no idea what this does, set to strict by default
    """

Trouvez-vous cela significatif? Postez vos bons / mauvais exemples à la connaissance de tous (et donnez-leur une réponse générale pour que ce soit accepté).

Était-ce utile?

La solution

Je suis d'accord avec "tout ce que vous ne pouvez pas distinguer de la signature de la méthode". Cela pourrait aussi vouloir dire ce qu’une méthode / fonction retourne.

Vous pouvez également utiliser la Sphinx (ainsi que la syntaxe reStructuredText) à des fins de documentation dans vos docstrings. De cette façon, vous pourrez facilement l'inclure dans votre documentation. Pour un exemple, consultez par exemple repoze.bfg qui l'utilise abondamment ( exemple de fichier , exemple de documentation ).

Une autre chose que l'on peut mettre dans docstrings est également la doctests . Cela pourrait avoir un sens esp. pour les docstrings de module ou de classe, vous pouvez aussi montrer de cette façon comment l'utiliser et le tester en même temps.

Autres conseils

De PEP 8 :

  

Conventions pour écrire de bonnes chaînes de documentation (a.k.a.   Les "docstrings" sont immortalisés dans le PEP 257 .

     
      
  • Écrire des docstrings pour tous les modules, fonctions, classes et méthodes publics. Les docstrings ne sont pas nécessaires pour les méthodes non publiques, mais vous   devrait avoir un commentaire qui décrit ce que fait la méthode. Ce   le commentaire doit apparaître après le mot-clé "def" ligne.
    •   
  • PEP 257 décrit de bonnes conventions en matière de docstring. Notez que le plus important, les """ " qui se termine un docstring multiligne devrait être sur un   ligne par elle-même et de préférence précédée d’une ligne vierge.
    •   
  • Pour un document de ligne, il est correct de conserver la fermeture """. sur la même ligne.
    •   

Ce qui devrait y aller:

Tout ce que vous ne pouvez pas distinguer de la signature de la méthode. Dans ce cas, le seul bit utile est: displayName - s'il est vide, le nom du champ est défini.

Recherchez dans la documentation de numpy de bons exemples (par exemple, http: / /github.com/numpy/numpy/blob/master/numpy/core/numeric.py ).

Les docstrings sont divisés en plusieurs sections et se présentent comme suit: 

Compute the sum of the elements of a list.

Parameters
----------
foo: sequence of ints
   The list of integers to sum up.

Returns
-------
res: int
   sum of elements of foo

See also
--------
cumsum:  compute cumulative sum of elemenents

Les choses les plus frappantes que je puisse penser à inclure dans une documentation sont les choses qui ne sont pas évidentes. Cela inclut généralement des informations de type ou des exigences de capacité - par exemple. "Nécessite un objet de type fichier". Dans certains cas, cela apparaît clairement à partir de la signature, pas dans d’autres.

Une autre chose utile que vous pouvez ajouter à vos docstrings est un doctest .

J'aime utiliser la documentation pour décrire de manière aussi détaillée que possible le fonctionnement de la fonction, en particulier le comportement dans les cas de coin (cas à la frontière, par exemple). Idéalement, un programmeur utilisant la fonction ne devrait jamais avoir à consulter le code source - en pratique, cela signifie que lorsqu'un autre programmeur doit consulter le code source pour comprendre en détail le fonctionnement de la fonction, ce détail aurait probablement dû être mentionné dans la documentation. Comme Freddy l'a dit, tout ce qui n'ajoute aucun détail à la signature de la méthode ne devrait probablement pas faire partie d'une chaîne de documentation.

Généralement, le but de l'ajout d'une chaîne de documentation au début de la fonction est de décrire la fonction, ses fonctions, son contenu renvoyé et une description des paramètres. Vous pouvez ajouter des détails d'implémentation si nécessaire. Même vous pouvez ajouter des détails sur l'auteur qui a écrit le code pour le futur développeur.

Licencié sous: CC-BY-SA avec attribution
Non affilié à StackOverflow
scroll top