Méthodes conseillées pour la fonction et la classe pour Python

Question

Je suis à la recherche pour les meilleures pratiques pour la fonction/classe/documentation du module, c'est à dire des commentaires dans le code lui-même. Idéalement, je voudrais un modèle de commentaire qui est à la fois lisibles et exploitables par la documentation Python utilitaires.

J'ai lu la documentation Python sur docstrings: http://docs.python.org/tutorial/controlflow.html.

Je comprends ceci:

"La première ligne doit toujours être un résumé bref et concis de l'objet. Par souci de concision, il ne devrait pas indiquer explicitement le nom de l'objet ou du type, puisque ceux-ci sont disponibles par d'autres moyens (sauf si le nom se trouve être un verbe décrivant une fonction de l'opération). Cette ligne doit commencer avec une lettre majuscule et se terminer par un point.

Si il y a plus de lignes dans la chaîne de documentation, la deuxième ligne doit être vide, visuellement séparant le résumé du reste de la description."

Cette phrase a besoin d'un peu plus d'explication:

"Les lignes suivantes doivent être d'un ou de plusieurs paragraphes décrivant l'objet de conventions d'appel, ses effets secondaires, etc."

Plus précisément, je suis à la recherche d'exemples de bien commenté de fonctions et de classes.

Answer 1

Vous devez utiliser reStructuredText et découvrez les Sphinx balisage des constructions. Tous les cool kids sont en train de faire.

Vous devez suivre docstring conventions. c'est à dire

Il prescrit de la fonction ou de la méthode effet comme une commande ("Faites ceci", "De retour").

Vous devriez éviter de vous répéter inutilement ou à expliquer le caractère éminemment évident. Exemple de ce qu'il ne faut pas faire:

def do_things(verbose=False):
    """Do some things.
    :param verbose: Be verbose (give additional messages).
    """
    raise NotImplementedError

Si vous voulais décrire quelque chose de non-évident que ça serait une autre histoire; par exemple, que verbose provoque des messages pour se produire sur stdout ou logging flux. Ce n'est pas spécifique à Python, mais résulte de plus de main-ondulés des idéaux tels que l'auto-documentation du code et du code, de la documentation SÈCHE.

Essayez d'éviter de mentionner les types spécifiques si possible (abstraite ou une interface-tels que les types sont généralement d'accord). Mentionner protocoles est généralement plus utile du duck-typing point de vue (c'est à dire "itératif" au lieu de set, ou "mutable séquence ordonnée" au lieu de list). J'ai vu un peu de code qui est très littéral et lourd WRT l' :rtype: et de la :type param: de la fonction au niveau de la documentation, que j'ai trouvé pour être en désaccord avec le duck-typing mentalité.

Answer 2

Comme dit Emji, Django est un bon projet à suivre pour claire, cohérente guides de style.

Par exemple, leurs Contribuer à Django style guide va même jusqu'à décrire la façon dont ils aimeraient voir la documentation. Plus précisément, ils mentionnent:

Dans les docstrings, utiliser des mots clés tels que:

def foo():
    """
    Calculates something and returns the result.
    """
    pass

Voici un exemple de ce qu'il ne faut pas faire:

def foo():
    """
    Calculate something and return the result.
    """
    pass

Answer 3

Je pense que la meilleure ressource sera la documentation de Python

Citation:

This document describes the style guide for our documentation, the custom reStructuredText markup introduced to support Python documentation and how it should be used, as well as the Sphinx build system.

Sphinx : Le générateur de documentation officiel Python

Answer 4

La meilleure façon d'apprendre les pratiques de documentation consiste probablement à examiner le code source d'un projet bien connu. Comme le Djangoproject .