web-dev-qa-db-fra.com

Y a-t-il un consensus sur ce qui doit être documenté dans les classes et les docstrings __init__?

Je n'ai trouvé aucune meilleure pratique sur ce qui devrait être documenté dans les classes et les docstrings __init__. Parfois, je trouve que les arguments du constructeur sont déjà documentés dans les classes docstring, parfois ils sont décrits dans la docstring __init__. Je préfère décrire la construction dans les classes docstring, car c'est ce que vous appelez lors de la création d'une nouvelle instance. Mais que faut-il alors documenter dans la docstring des méthodes __init__?

modifier:

Je connais le google styleguide et le google docstring style example , mais les deux ne répondent pas à ma question. L'exemple de style docstring dit

La méthode __init__ Peut être documentée soit dans la docstring de niveau classe, soit en tant que docstring dans la méthode __init__ Elle-même. L'une ou l'autre forme est acceptable, mais les deux ne doivent pas être mélangées. Choisissez une convention pour documenter la méthode __init__ Et soyez cohérent avec elle.

Mais si je choisis de mettre la docstring de la fonction __init__ Dans la docstring de niveau classe, que doit contenir la docstring __init__?

pythondocstringcode-documentation
31
causa prima

L'utilisation réelle de la classe est initialisée par une commande comme SampleClass(args), et aucun utilisateur ne va jamais taper SampleClass.__init__(args), donc du point de vue de l'utilisateur final, lorsqu'ils sont confus, ils sont beaucoup plus susceptibles de taper

help(SampleClass)

au lieu de

help(SampleClass.__init__)

Je pense donc qu'il est logique de mettre toute la documentation dans la docstring de SampleClass.
Et dans la docstring de __init__ Mettez "Veuillez voir help(SampleClass) pour plus d'informations" juste au cas où il y aurait une chance que quelqu'un (ou programme) le regarde.

5
Demis

J'essaie personnellement d'utiliser le google styleguide lorsque c'est possible

Lorsque vous créez une nouvelle instance avec __init__ il faut documenter quelles variables membres sont initialisées. Ensuite, d'autres personnes savent à quoi s'attendre lorsqu'elles ont besoin d'y accéder plus tard dans leur code.

Échantillon du guide de style Google:

class SampleClass(object):
    """Summary of class here.

    Longer class information....
    Longer class information....

    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

    def __init__(self, likes_spam=False):
        """Inits SampleClass with blah."""
        self.likes_spam = likes_spam
        self.eggs = 0

    def public_method(self):
        """Performs operation blah."""
4
salomonderossi

Je n'ai connaissance d'aucun consensus sur ce point.

Cependant, le module sphinx autodoc permet de générer de la documentation à partir de votre docstring. Par conséquent, il a tendance à appliquer une documentation cohérente docstring.

Dans votre cas, je documenterais ce que le class est et les arguments du constructeur dans le class docstring comme:

class MyClass:
    """I am a class.
    I do funny stuff

    :type tags: dict
    :param tags: A dictionary of key-value pairs
    """

    def __init__(tags):
        self.tags = tags
3
Oleiade

Numpy dit que vous devez documenter le __init__ dans le document de classe. https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

Voici un exemple où vous pouvez voir où __init__ n'a pas de docstring. Au lieu de cela, il apparaît dans le document de classe. https://github.com/numpy/numpy/blob/master/numpy/core/records.py

1
Brig

exemple de Google docstring répond à votre question. Si vous choisissez de documenter votre __init__ méthode dans la docstring de niveau classe, la __init__ docstring est laissé vide. Par exemple:

class ExampleError(Exception):
    """Exceptions are documented in the same way as classes.

    The __init__ method may be documented in either the class level
    docstring, or as a docstring on the __init__ method itself.

    Either form is acceptable, but the two should not be mixed. Choose one
    convention to document the __init__ method and be consistent with it.

    Note:
        Do not include the `self` parameter in the ``Args`` section.

    Args:
        msg (str): Human readable string describing the exception.
        code (:obj:`int`, optional): Error code.

    Attributes:
        msg (str): Human readable string describing the exception.
        code (int): Exception error code.

    """

    def __init__(self, msg, code):
        self.msg = msg
        self.code = code

Alternativement, divisez cette docstring entre le niveau de la classe et __init__ docstrings.

0
geher

Google a son propre guide de style pour Python, ce qui n'est pas une mauvaise chose. Voici un lien avec ce qu'ils considèrent comme les meilleures pratiques pour les chaînes de doc: http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

0
coralvanda

Il y a une réponse officielle, dans le PEP 257 (le docstring PEP), qui fait sans doute autorité:

Le constructeur de classe doit être documenté dans la docstring pour sa méthode __init__.

C'est tout à fait logique, car c'est la procédure habituelle pour les fonctions et les méthodes, et __init__() n'est pas une exception.

Par conséquent, cela place le code et sa documentation au même endroit, ce qui facilite la maintenance.

Enfin, les outils qui affichent la documentation à l'utilisateur (comme Jupyter) sont plus susceptibles d'afficher correctement la documentation de votre code.

0
Eric O Lebigot