Comment écrire des docstrings significatifs?
Quoi, à votre avis, est un docstring significatif? Qu'attendez-Vous d'être décrite?
Par exemple, considérez __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? Publiez vos bons / mauvais exemples pour tout savoir (et une réponse générale afin qu'il puisse être accepté).
7 réponses
Je suis d'accord avec "tout ce que vous ne pouvez pas dire de la signature de la méthode". Cela peut également signifier expliquer ce qu'une méthode/fonction retourne.
Vous pouvez également utiliser Sphinx (et la syntaxe reStructuredText) à des fins de documentation dans vos docstrings. De cette façon, vous pouvez l'inclure dans vos documents facilement. Pour un exemple, consultez par exemple repoze.bfg, qui utilise cette profondeur (exemple de fichier, documentation exemple).
Autre la chose que l'on peut mettre dans docstrings est aussi doctests. Cela pourrait avoir du sens esp. pour le module ou la classe docstrings comme vous pouvez également montrer de cette façon comment l'utiliser et avoir ce testable en même temps.
À Partir de PEP 8:
Conventions pour écrire de bonnes chaînes de documentation (alias "docstrings") sont immortalisés dans PEP 257 .
- écrivez des docstrings pour tous les modules, fonctions, classes et méthodes publics. Docstrings ne sont pas nécessaires pour les méthodes non publiques, mais vous devrait avoir un commentaire qui décrit la méthode. Ce le commentaire doit apparaître après la ligne "def".
- PEP 257 décrit un bon docstring Convention. Notez que le plus important, le """ qui termine un docstring multiligne devrait être sur un ligne seule, et de préférence précédée d'une ligne vierge.
- pour un liner docstrings, il est correct de garder la fermeture """ sur la même ligne.
Ce qui devrait y aller:
Tout ce que vous ne pouvez pas dire à partir de la signature de la méthode. Dans ce cas, le seul bit utile est: displayName - si vide sera défini sur nom de champ.
Consultez les docstrings de numpy pour 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 ressemblent à ceci:
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 auxquelles je peux penser à inclure dans un docstring sont les choses qui ne sont pas évidentes. Habituellement, cela inclut les informations de type, ou les exigences de capacité-par exemple. "Requiert un fichier-comme l'objet". Dans certains cas, cela sera évident à partir de la signature, pas dans d'autres cas.
Une Autre chose utile que vous pouvez mettre dans votre docstrings est un doctest.
J'aime utiliser la documentation pour décrire avec le plus de détails possible ce que fait la fonction, en particulier le comportement dans les cas de coin (alias cas de bord). Idéalement, un programmeur utilisant la fonction ne devrait jamais avoir à regarder le code source - en pratique, cela signifie que chaque fois qu'un autre programmeur doit regarder le code source pour comprendre certains détails sur le fonctionnement de la fonction, ce détail aurait probablement dû être mentionné dans la documentation. Comme Freddy a dit, tout ce qui n'ajoute aucun détail à la signature de la méthode ne devrait probablement pas être dans une chaîne de documentation.
Généralement, le but de l'ajout d'une chaîne doc dans le démarrage de la fonction est de décrire la fonction, ce qu'elle fait, ce qu'elle retournerait et la 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.