Commentaires Python3

En Python, les commentaires n'affectent pas l'exécution du programme, mais ils rendent le code plus facile à lire et à comprendre.

Les commentaires en Python incluent :Commentaires sur une seule ligneetCommentaires multilignes。

Commentaires sur une seule ligne

En Python, les commentaires sur une seule ligne utilisent## au début,#Tout texte après le symbole # est traité comme un commentaire et ne sera pas exécuté par l'interpréteur.

Exemple

# Ceci est un commentaire
print("Hello, World!")
# Ceci est aussi un commentaire

Commentaires multilignes

En Python, les chaînes multilignes (blocs de texte entourés de trois guillemets simples'''ou de trois guillemets doubles""") peuvent être utilisées comme commentaires multilignes.

1. Utilisation de trois guillemets simples

Exemple

#!/usr/bin/python3

'''
Ceci est un commentaire multiligne utilisant trois guillemets simples
Ceci est un commentaire multiligne utilisant trois guillemets simples
Ceci est un commentaire multiligne utilisant trois guillemets simples
'''
print("Hello, World!")

2. Utilisation de trois guillemets doubles

Exemple

#!/usr/bin/python3

"""
Ceci est un commentaire multiligne utilisant trois guillemets doubles
Ceci est un commentaire multiligne utilisant trois guillemets doubles
Ceci est un commentaire multiligne utilisant trois guillemets doubles
"""
print("Hello, World!")

Remarque: Bien que des chaînes multilignes soient utilisées ici comme commentaires multilignes, ce sont en réalité des chaînes. Tant que nous ne les utilisons pas, elles n'affecteront pas l'exécution du programme.

Ces chaînes peuvent être placées à certains endroits dans le code sans être réellement exécutées, ce qui permet d'obtenir l'effet de commentaires.

Remarques sur les commentaires multilignes

En Python, les commentaires multilignes sont définis par trois guillemets simples'''ou trois guillemets doubles"""pour les définir,Ce type de commentaire ne peut pas être imbriqué.。

Lorsque vous démarrez un bloc de commentaires multilignes, Python traitera toutes les lignes suivantes comme des commentaires jusqu'à ce qu'il rencontre un autre ensemble de trois guillemets simples ou trois guillemets doubles.

L'imbrication de commentaires multilignes provoquera des erreurs de syntaxe :

Exemple (incorrect)

'''
Ceci est le commentaire multiligne externe
Il peut contenir du contenu descriptif

    '''
Ceci est une tentative d'imbriquer un commentaire multiligne
Cela provoquera une erreur de syntaxe
    '''
'''

Dans cet exemple, les trois guillemets simples internes ne sont pas correctement reconnus comme la fin du commentaire multiligne, mais sont interprétés comme une chaîne ordinaire, ce qui conduira à une structure de code incorrecte.

Approche correcte : utiliser des commentaires monolignes pour l'imbrication

Exemple (correct)

'''
Ceci est le commentaire multiligne externe
Il peut contenir du contenu descriptif

# Ceci est un commentaire monoligne interne
# Il peut être imbriqué à l'intérieur d'un commentaire multiligne
'''

Docstring (chaînes de documentation)

La Docstring de Python (chaîne de documentation) est un commentaire spécial utilisé pour ajouter de la documentation aux fonctions, aux classes, aux modules, etc. Elle est similaire au Javadoc de Java, mais plus puissante et flexible.

Contrairement aux commentaires ordinaires,les Docstrings sont accessibles directement via__doc__l'attribut __doc__,ou vous pouvez utiliser lahelp()fonction help() pour afficher.

Syntaxe de base

Les docstrings utilisent trois guillemets doubles"""ou trois guillemets simples'''pour les encadrer, et sont placées au début d'une fonction, d'une classe ou d'un module.

Exemple

def add(a, b):
    """Renvoie la somme de deux nombres"""
    return a + b

# Accès via l'attribut __doc__
print(add.__doc__)  # Sortie : Renvoie la somme de deux nombres

Utilisation de help() pour consulter la documentation

Exemple

def add(a, b):
    """Renvoie la somme de deux nombres"""
    return a + b

# Utiliser la fonction help()
help(add)

Sortie attendue :

Help on function add in module __main__:

add(a, b)
    返回两数之和

Utilisation du module inspect pour extraire la documentation

La bibliothèque standard de Python fournit leinspectmodule inspect, qui peut directement extraire le contenu de la documentation :

Exemple

import inspect

def add(a, b):
    """Renvoie la somme de deux nombres"""
    return a + b

# Utilisez inspect.getdoc() pour obtenir la documentation
print(inspect.getdoc(add))  # Sortie : Renvoie la somme de deux nombres

Sortie attendue :

Return the sum of two numbers

Docstring multiligne

Pour les fonctions complexes, vous pouvez utiliser des Docstrings multilignes :

Exemple

def calculate(a, b, operation="add"):
    """
Effectuer des opérations mathématiques

Paramètres :
a : Le premier nombre
b : Le deuxième nombre
operation : Le type d'opération, facultatif "add", "subtract", "multiply"

Retourne :
Le résultat du calcul
    """
    if operation == "add":
        return a + b
    elif operation == "subtract":
        return a - b
    elif operation == "multiply":
        return a * b
    else:
        raise ValueError("Opération non prise en charge")

# Consulter la documentation complète
help(calculate)

Sortie attendue :

Help on function calculate in module __main__:

calculate(a, b, operation='add')
    执行数学运算

    Arguments:
        a: 第一个数字
        b: 第二个数字
        operation: 操作类型，可选 "add", "subtract", "multiply"

    返回:
        计算结果

Docstring de classe

Les docstrings peuvent également être utilisées pour les classes :

Exemple

class Person:
    """Classe Person, utilisée pour représenter les informations de base d'une personne"""

    def __init__(self, name, age):
        """
Initialiser un objet personne

Paramètres :
name: Name
age: Age
        """
        self.name = name
        self.age = age

    def introduce(self):
        """Présenter cette personne"""
        return f"Je m'appelle {self.name}, et j'ai {self.age} ans"

# Accéder à la documentation de la classe
print(Person.__doc__)

# Accéder à la documentation de la méthode
print(Person.introduce.__doc__)

Sortie attendue :

Person class, used to represent basic information about a person
Introduce this person

Conventions de docstring

Il existe plusieurs styles de docstring en Python. Les plus courants incluent :

  • Style Google: utilise des espaces pour l'indentation, avec des libellés clairs pour les paramètres et les valeurs de retour.
  • Style Sphinx/reST: utilise un deux-points au début, comme:param name:。
  • Style NumPy: similaire au style Google, mais avec une mise en forme légèrement différente.

Il est recommandé de choisir un seul style dans votre projet et de le conserver de manière cohérente.

Autres extensions