Quelle est la bonne façon de commenter les fonctions en python?

Question

Est-il une méthode généralement acceptée pour ce faire? Est-ce acceptable:

#########################################################
# Create a new user
#########################################################
def add(self):

Answer 1

La bonne façon de le faire est de fournir une docstring. De cette façon, help(add) également cracher votre commentaire.

def add(self):
"""Create a new user.
Line 2 of comment...
And so on... """

Ce sont trois des guillemets pour ouvrir le commentaire et un autre de trois guillemets à la fin.

Voir: http://diveintopython3.ep.io/your-first-python-program.html#docstrings

Answer 2

Utiliser une docstring, comme d'autres l'ont déjà écrit.

Vous pouvez même aller plus loin et ajouter un doctest à votre docstring, faire des tests automatisés de vos fonctions d'un composant logiciel enfichable.

Answer 3

Utiliser une docstring.

Answer 4

Lu sur l'utilisation de docstrings dans votre code python.

Comme par le Python Docstring Conventions:

La docstring pour une fonction ou une méthode doit résumer son comportement et de documenter ses arguments, la valeur de retour(s), les effets secondaires, les exceptions soulevées, et les restrictions sur le moment où il peut être appelé (si applicable). Les arguments optionnels doivent être indiqués. Il doit être documenté si le mot-clé arguments font partie de l'interface.

Il n'y aura pas de règle d'or, mais plutôt de fournir des commentaires qui signifie quelque chose pour les autres les développeurs de votre équipe (si vous en avez un) ou même pour vous-même lorsque vous revenez à lui de six mois sur la route.

Answer 5

Je pencherais pour une documentation pratique qui s'intègre avec un outil de Documentation tels que le Sphinx.

La première étape est d'utiliser un docstring:

def add(self):
 """ Method which adds stuff
 """