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

Existe-t-il un moyen généralement accepté de commenter les fonctions en Python? Est-ce que ce qui suit est acceptable?

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

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

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

Cela fait trois guillemets pour ouvrir le commentaire et trois autres guillemets pour le terminer. Vous pouvez également utiliser n'importe quelle chaîne Python valide. Il n'a pas besoin d'être multiligne et les guillemets doubles peuvent être remplacés par des guillemets simples.

Voir: PEP 257

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

Vous pouvez même aller plus loin et ajouter un doctest à votre docstring, ce qui rend les tests automatisés de vos fonctions un jeu d'enfant.

Utilisez une docstring :

Une chaîne littérale qui se produit comme première instruction dans une définition de module, fonction, classe ou méthode. Une telle docstring devient l' __doc__attribut spécial de cet objet.

Tous les modules devraient normalement avoir des docstrings, et toutes les fonctions et classes exportées par un module devraient également avoir des docstrings. Les méthodes publiques (y compris le __init__constructeur) doivent également avoir des docstrings. Un package peut être documenté dans le module docstring du __init__.pyfichier dans le répertoire package.

Les chaînes littérales apparaissant ailleurs dans le code Python peuvent également servir de documentation. Ils ne sont pas reconnus par le compilateur de bytecode Python et ne sont pas accessibles en tant qu'attributs d'objet d'exécution (c'est-à-dire non affectés à __doc__), mais deux types de docstrings supplémentaires peuvent être extraits par des outils logiciels:

1. Les littéraux de chaîne apparaissant immédiatement après une simple affectation au niveau supérieur d'un module, d'une classe ou d'une __init__méthode sont appelés "docstrings d'attribut".
2. Les littéraux de chaîne apparaissant immédiatement après une autre docstring sont appelés "docstrings supplémentaires".

Veuillez consulter la PEP 258 , "Docutils Design Specification" [2] , pour une description détaillée de l'attribut et des docstrings supplémentaires ...

Les principes d'un bon commentaire sont assez subjectifs, mais voici quelques lignes directrices:

• Les commentaires de fonction doivent décrire l' intention d'une fonction, pas l'implémentation
• Décrivez toutes les hypothèses formulées par votre fonction concernant l'état du système. S'il utilise des variables globales (tsk, tsk), listez-les.
• Attention à l'art ASCII excessif . Avoir de longues chaînes de hachages peut sembler rendre les commentaires plus faciles à lire, mais ils peuvent être ennuyeux à gérer lorsque les commentaires changent
• Tirez parti des fonctionnalités du langage qui fournissent une `` documentation automatique '', c'est-à-dire des docstrings en Python, POD en Perl et Javadoc en Java

Découvrez comment utiliser des docstrings dans votre code Python.

Conformément aux conventions docstring Python :

La docstring d'une fonction ou d'une méthode doit résumer son comportement et documenter ses arguments, valeur (s) de retour, effets secondaires, exceptions levées et restrictions sur le moment où elle peut être appelée (le cas échéant). Les arguments facultatifs doivent être indiqués. Il convient de documenter si les arguments de mots clés font partie de l'interface.

Il n'y aura pas de règle d'or, mais faites plutôt des commentaires qui signifient quelque chose aux autres développeurs de votre équipe (si vous en avez un) ou même à vous-même lorsque vous y reviendrez six mois plus tard.

J'opterais pour une pratique de documentation qui s'intègre à un outil de documentation tel que Sphinx .

La première étape consiste à utiliser un docstring:

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

J'irais plus loin que de simplement dire "utiliser une docstring". Choisissez un outil de génération de documentation, tel que pydoc ou epydoc (j'utilise epydoc dans pyparsing), et utilisez la syntaxe de balisage reconnue par cet outil. Exécutez souvent cet outil pendant que vous faites votre développement, pour identifier les failles dans votre documentation. En fait, vous pourriez même bénéficier de l'écriture des docstrings pour les membres d'une classe avant d' implémenter la classe.

Utilisez des docstrings .

Voici la convention suggérée intégrée dans PyCharm pour les commentaires de description de fonction:

def test_function(p1, p2, p3):
    """
    my function does blah blah blah

    :param p1: 
    :param p2: 
    :param p3: 
    :return: 
    """

Bien que je convienne que cela ne devrait pas être un commentaire, mais une docstring comme le suggèrent la plupart (toutes?) Des réponses, je veux ajouter numpydoc (un guide de style docstring) .

Si vous le faites comme ça, vous pouvez (1) générer automatiquement de la documentation et (2) les gens le reconnaîtront et auront plus de facilité à lire votre code.

Vous pouvez utiliser trois guillemets pour le faire.

Vous pouvez utiliser des guillemets simples:

def myfunction(para1,para2):
  '''
  The stuff inside the function
  '''

Ou guillemets doubles:

def myfunction(para1,para2):
  """
  The stuff inside the function
  """