Comment commenter en Python

Mise à jour en juillet 2021

Présentation

Une compétence clé dans l'écriture de code est la capacité d'utiliser des commentaires. Les commentaires sont des lignes que les compilateurs et les interpréteurs ignorent et que les développeurs utilisent pour laisser des notes sur la fonction du code. De plus, ils peuvent également être utilisés pour désactiver des parties du code.

Ce guide vous montrera comment utiliser efficacement les commentaires en Python.

Prérequis

Un environnement de programmation Python fonctionnel
La possibilité de créer et de modifier des fichiers Python

Syntaxe des commentaires Python

Pour ajouter ou marquer une ligne comme commentaire, commencez par un dièse (# ) et un espace :

# This is a sample comment.

L'utilisation du signe dièse pour commencer la ligne indique au système d'ignorer tout ce qui se trouve dans cette ligne. Lorsque l'application s'exécute, le programme prétend que ces lignes n'existent pas. Cependant, vous pouvez toujours le voir lorsque vous modifiez le fichier.

Par exemple, dans Hello World programme ci-dessous :

# Display the text "Hello, World!" on the screen.
print("Hello, World!")

Le système exécute le code print("Hello, World") à la ligne quatre, alors que la ligne au-dessus explique ce que le code est censé faire.

Vous pouvez définir n'importe quelle ligne comme commentaire et en utiliser autant que vous le souhaitez. Si votre code comporte différents blocs, vous pouvez utiliser un commentaire pour expliquer chacun d'eux. Par exemple :

# Define a variable flowers as a list of strings.
flowers = [‘rose’, ‘carnation’, ‘daisy’, ‘marigold’, ‘tulip’, ‘sunflower’]

# Create a for loop to iterate through flowers list, and displays each string item.
for flower in flowers:
            print(flower)

Bloc de commentaire Python

Bloquer les commentaires sont des commentaires plus longs composés de plusieurs lignes consécutives. Un développeur les utilise pour expliquer un code plus complexe, en particulier lorsqu'il travaille en équipe.

Pour marquer une série de lignes comme commentaire, ajoutez un dièse + espace au début de chaque ligne :

# This is a comment
# that runs on to
# multiple lines.

Certains éditeurs de texte ou de code pour la programmation (comme Notepad++ ou Atom) vous permettent de surligner le texte, puis de cliquer avec la souris pour marquer le bloc comme commentaire. Ces outils peuvent vous faire gagner du temps en commentant chaque ligne.

Commentaire multiligne Python

En général, il est recommandé d'utiliser # au début de chaque ligne pour la marquer comme commentaire. Cependant, commenter une grande section prend beaucoup de temps et vous aurez peut-être besoin d'un moyen rapide de commenter une section entière. Dans de tels cas, vous pouvez utiliser des commentaires multilignes .

Les chaînes multilignes ne fonctionnent pas comme des commentaires Python traditionnels, car il n'y a pas de fonctionnalité multiligne officielle. À la place, utilisez des chaînes multilignes entourées de guillemets triples (""" ) pour obtenir une fonction similaire.

Par exemple :

def addition_test(a, b):
    result = a + b
    """
    This is a block
    of commented lines.
    They aren’t parsed and interpreted by the compiler.
    """
return result

Cette méthode crée une constante de texte sans fonction, pas un vrai commentaire. Tant que vous n'ajoutez rien qui accède à cette chaîne de texte, cela fonctionne comme un commentaire normal.

Les guillemets triples peuvent être délicats car, dans certaines circonstances, ils créent une docstring si un guillemet triple :

suit une signature de fonction,
suit une définition de classe,
se trouve au début d'un module.

Si vous placez """ dans l'un des endroits répertoriés ci-dessus, Python le lit comme un dosctring . Docstrings vous permet de mettre du texte lisible par l'homme dans le projet. Ceci est généralement utilisé pour créer une documentation faisant partie de l'application et accessible au moment de l'exécution.

Commentaire en ligne Python

Vous pouvez commenter dans la même ligne qu'un morceau de code en utilisant un commentaire en ligne . Le meilleur moment pour utiliser cette option est lors de l'explication d'une opération compliquée.

Utilisez un commentaire en ligne pour indiquer l'endroit exact que vous souhaitez clarifier. Ajoutez le dièse standard + espace pour signifier un commentaire en ligne :

function
    set variable
    run command
    run additional command        # Tricky part:  The program breaks if this line is removed.

Les commentaires en ligne sont utilisés pour ajouter du contexte aux personnes qui lisent le code. Par exemple, vous pouvez expliquer le but d'une variable ou laisser une note sur le type de variable créée. Il peut également être utile d'expliquer pourquoi une commande particulière est utilisée, comme dans l'exemple ci-dessus.

Sortie de commentaire Python

Étant donné que les commentaires rendent le texte invisible pour l'analyseur, vous pouvez les utiliser pour désactiver les commandes. Cela vous permet de tester des segments de code avec et sans nouveaux ajouts.

Par exemple, dans ce simple programme de lancer de dés, il y a une section qui est commentée. Si vous supprimez le signe dièse, vous activez le code pour le tester.

import random
min = 1
max = 6

roll_again = "yes"

while roll_again == "yes" or roll_again == "y":
     print "Rolling the dice..."
     print "The values are...."
     print random.randint(min, max)
     print random.randint(min, max)

# Add two random numbers together for a sum
# while roll_again == “yes” or roll_again == “y”:
    # print ”Rolling the dice…”
    # print “You rolled a “
    # print random.randint(min,max) + random.randint(min, max)

    roll_again = raw_input("Roll the dice again?")

Pourquoi les commentaires sont-ils importants en Python ?

Les commentaires peuvent vous aider :

Comprenez votre propre code lorsque vous y revenez après une longue période de temps.
Vous remettre à niveau plus rapidement.
Problèmes de débogage.
Comprendre certains choix de code lorsque vous travaillez au sein d'une équipe.
Éviter les problèmes potentiels en mettant l'accent sur l'importance d'une partie de code spécifique.

Bonnes pratiques pour les commentaires de code Python

Commentez à la même indentation que le code auquel vous faites référence. Cela permet de voir plus facilement à quoi vous faites référence.
Mettez à jour vos commentaires lorsque vous mettez à jour votre code. Les commentaires incorrects sont pires que l'absence de commentaires.
Utilisez des phrases complètes. Mettez des majuscules aux mots appropriés, sauf si vous faites référence à un identifiant (comme une variable). Ne modifiez jamais la casse d'un identifiant.
Les commentaires en bloc doivent être rédigés en phrases complètes, avec des points. Visez 80 mots par ligne ou moins.
Si vous avez plusieurs phrases dans un commentaire, utilisez un double espace entre les phrases.
Rédigez des commentaires en anglais.
Pour un commentaire de bloc avec plusieurs paragraphes, ajoutez une ligne vide entre les paragraphes avec une seule balise de commentaire précédant une ligne vide.
Pour les commentaires intégrés, laissez au moins deux espaces entre le code et le commentaire. Utilisez les commentaires en ligne avec parcimonie et évitez de les utiliser pour énoncer des évidences.

ÉVITER :

Ne commentez pas le code qui s'explique de lui-même. Respectez le principe d'écriture DRY (D pas R répétez Y nous-mêmes) et éviter WET (W rite E tout T wice) code et commentaires.
Évitez d'utiliser des commentaires pour expliquer un code confus :les commentaires doivent soutenir le code et non le justifier.