Python Language
Commentaires et documentation

Syntaxe

• # Ceci est un commentaire sur une seule ligne
• print ("") # Ceci est un commentaire en ligne
• "" "
  C'est
  un commentaire sur plusieurs lignes
  "" "

Remarques

Commentaires sur une seule ligne, inline et multiligne

Les commentaires sont utilisés pour expliquer le code lorsque le code de base lui-même n'est pas clair.

Python ignore les commentaires et n'exécute donc pas de code là-dedans, ni ne génère d'erreurs de syntaxe pour les phrases anglaises simples.

Les commentaires sur une seule ligne commencent par le caractère de hachage ( # ) et se terminent par la fin de la ligne.

• Commentaire sur une seule ligne:

# This is a single line comment in Python

• Commentaire en ligne:

print("Hello World")  # This line prints "Hello World"

• Les commentaires couvrant plusieurs lignes ont """ ou ''' à chaque extrémité. C'est la même chose qu'une chaîne multiligne, mais ils peuvent être utilisés comme commentaires:

"""
This type of comment spans multiple lines.
These are mostly used for documentation of functions, classes and modules.
"""

Accéder par programme à docstrings

Contrairement aux commentaires réguliers, Docstrings est stocké en tant qu'attribut de la fonction qu'ils documentent, ce qui signifie que vous pouvez y accéder par programmation.

Un exemple de fonction

def func():
    """This is a function that does nothing at all"""
    return

Le docstring est accessible en utilisant l'attribut __doc__ :

print(func.__doc__)

Ceci est une fonction qui ne fait rien du tout

help(func)

Aide sur la fonction func dans le module __main__ :

func()

Ceci est une fonction qui ne fait rien du tout

Un autre exemple de fonction

function.__doc__ n'est que le docstring réel en tant que chaîne, alors que la fonction help fournit des informations générales sur une fonction, y compris la docstring. Voici un exemple plus utile:

def greet(name, greeting="Hello"):
    """Print a greeting to the user `name`

    Optional parameter `greeting` can change what they're greeted with."""
    
    print("{} {}".format(greeting, name))

help(greet)

Aide sur la fonction greet dans le module __main__ :

greet(name, greeting='Hello')

Imprimer un message d'accueil au name de l'utilisateur
Paramètre optionnel greeting d' greeting peut changer ce qu'ils sont accueillis avec.

Avantages de docstrings sur les commentaires réguliers

Le simple fait de ne pas placer de docstring ou un commentaire régulier dans une fonction le rend moins utile.

def greet(name, greeting="Hello"):
    # Print a greeting to the user `name`
    # Optional parameter `greeting` can change what they're greeted with.
    
    print("{} {}".format(greeting, name))

print(greet.__doc__)

Aucun

help(greet)

Aide sur la fonction accueil dans le module principal :

greet(name, greeting='Hello')

Ecrire de la documentation à l'aide de docstrings

Un docstring est un commentaire multi-lignes utilisé pour documenter des modules, des classes, des fonctions et des méthodes. Il doit s'agir de la première déclaration du composant qu'il décrit.

def hello(name):
    """Greet someone.

    Print a greeting ("Hello") for the person with the given name.
    """

    print("Hello "+name)

class Greeter:
    """An object used to greet people.

    It contains multiple greeting functions for several languages
    and times of the  day.
    """

La valeur de docstring est accessible dans le programme et est, par exemple, utilisée par la commande help .

Conventions de syntaxe

PEP 257

PEP 257 définit une norme de syntaxe pour les commentaires docstring. Il permet essentiellement deux types:

• Docstrings à une ligne:

Selon le PEP 257, ils doivent être utilisés avec des fonctions courtes et simples. Tout est placé sur une ligne, par exemple:

def hello():
    """Say hello to your friends."""
    print("Hello my friends!")

Le docstring doit se terminer par un point, le verbe doit être sous la forme impérative.

• Docstrings multilignes:

Les docstrings multi-lignes doivent être utilisés pour des fonctions, modules ou classes plus longs et plus complexes.

def hello(name, language="en"):
    """Say hello to a person.

    Arguments:
    name: the name of the person
    language: the language in which the person should be greeted
    """

    print(greeting[language]+" "+name)

Ils commencent par un bref résumé (équivalent au contenu d'une docstring à une ligne) qui peut être sur la même ligne que les guillemets ou sur la ligne suivante, donnant des détails supplémentaires, des paramètres de liste et des valeurs de retour.

Remarque PEP 257 définit quelles informations doivent être données dans un document, il ne définit pas dans quel format il doit être donné. C'était la raison pour laquelle d'autres parties et des outils d'analyse de documentation spécifiaient leurs propres normes pour la documentation, dont certaines sont énumérées ci-dessous et dans cette question .

Sphinx

Sphinx est un outil permettant de générer de la documentation basée sur HTML pour les projets Python basés sur docstrings. Son langage de balisage utilisé est reStructuredText . Ils définissent leurs propres normes pour la documentation, pythonhosted.org en héberge une très bonne description . Le format Sphinx est par exemple utilisé par l' IDE pyCharm .

Une fonction serait documentée comme ceci en utilisant le format Sphinx / reStructuredText:

def hello(name, language="en"):
    """Say hello to a person.

    :param name: the name of the person
    :type name: str
    :param language: the language in which the person should be greeted
    :type language: str
    :return: a number
    :rtype: int
    """

    print(greeting[language]+" "+name)
    return 4

Guide de style Google Python

Google a publié le guide de style Google Python qui définit les conventions de codage pour Python, y compris les commentaires de la documentation. En comparaison avec Sphinx / reST, beaucoup de gens disent que la documentation selon les directives de Google est mieux lisible par l'homme.

La page pythonhosted.org mentionnée ci-dessus fournit également des exemples de documentation conforme au Guide de style de Google.

En utilisant le plug-in Napoleon , Sphinx peut également analyser la documentation dans le format compatible avec Google Style Guide.

Une fonction serait documentée comme ceci en utilisant le format Guide de style de Google:

def hello(name, language="en"):
    """Say hello to a person.

    Args:
        name: the name of the person as string
        language: the language code string

    Returns:
        A number.
    """

    print(greeting[language]+" "+name)
    return 4