Comment écrire des commentaires en Python 3

Introduction

Les commentaires sont des lignes qui existent dans les programmes informatiques et qui sont ignorées par les compilateurs et les interprètes. L'utilisation de commentaires dans les programmes peut rendre le code plus lisible pour les humains, car elle fournit certaines informations ou explications sur ce que chaque partie d'un programme fait.

Selon l'objectif de votre programme, les commentaires peuvent servir de notes pour vous-même ou de rappels, ou ils peuvent être écrits dans l'intention que d'autres programmeurs puissent comprendre ce que fait votre code.

En général, il est conseillé d'écrire des commentaires pendant que vous écrivez ou mettez à jour un programme, car il est facile d'oublier votre processus de réflexion plus tard, et les commentaires écrits ultérieurement peuvent être moins utiles à long terme.

Prérequis

Vous devriez avoir Python 3 installé et un environnement de programmation configuré sur votre ordinateur ou serveur. Si vous n'avez pas encore configuré d'environnement de programmation, vous pouvez vous référer aux guides d'installation et de configuration pour un environnement de programmation local ou pour un environnement de programmation sur votre serveur approprié à votre système d'exploitation (Ubuntu, CentOS, Debian, etc.)

Commentaire de syntaxe

Les commentaires en Python commencent par un signe dièse (#) et un caractère d'espacement, et continuent jusqu'à la fin de la ligne.

En général, les commentaires ressembleront à ceci :

# This is a comment

Parce que les commentaires ne s'exécutent pas, lorsque vous lancez un programme, vous ne verrez aucune indication du commentaire. Les commentaires sont dans le code source pour que les humains les lisent, pas pour que les ordinateurs les exécutent.

Dans un programme « Hello, World ! », un commentaire peut ressembler à ceci :

# Print “Hello, World!” to console
print("Hello, World!")

Dans une boucle for qui itère sur une liste, les commentaires peuvent ressembler à ceci :

# Define sharks variable as a list of strings
sharks = ['hammerhead', 'great white', 'dogfish', 'frilled', 'bullhead', 'requiem']

# For loop that iterates over sharks list and prints each string item
for shark in sharks:
   print(shark)

Les commentaires doivent être faits au même niveau d'indentation que le code qu'ils commentent. C'est-à-dire qu'une définition de fonction sans indentation aurait un commentaire sans indentation, et chaque niveau d'indentation suivant aurait des commentaires alignés avec le code qu'ils commentent.

Par exemple, voici comment la fonction again() du tutoriel Comment créer un programme de calculatrice simple en Python 3 est commentée, avec des commentaires suivant chaque niveau d'indentation du code :

...
# Define again() function to ask user if they want to use the calculator again
def again():

    # Take input from user
    calc_again = input('''
Do you want to calculate again?
Please type Y for YES or N for NO.
''')

    # If user types Y, run the calculate() function
    if calc_again == 'Y':
        calculate()

    # If user types N, say good-bye to the user and end the program
    elif calc_again == 'N':
        print('See you later.')

    # If user types another key, run the function again
    else:
        again()

Les commentaires sont faits pour aider les programmeurs, qu'il s'agisse du programmeur d'origine ou de quelqu'un d'autre utilisant ou collaborant sur le projet. Si les commentaires ne peuvent pas être correctement entretenus et mis à jour avec la base de code, il vaut mieux ne pas inclure de commentaire plutôt que d'écrire un commentaire qui contredit ou contredira le code.

Lorsque vous commentez du code, vous devriez chercher à répondre au pourquoi du code plutôt qu'au quoi ou au comment. Sauf si le code est particulièrement complexe, regarder le code peut généralement indiquer ce que fait le code ou comment il le fait.

Commentaires en bloc

Les commentaires en bloc peuvent être utilisés pour expliquer un code plus complexe ou un code que vous ne vous attendez pas à ce que le lecteur connaisse. Ces commentaires plus longs s'appliquent à une partie ou à la totalité du code qui suit, et sont également indentés au même niveau que le code.

Dans les commentaires en bloc, chaque ligne commence par le signe dièse et un espace. Si vous devez utiliser plus d'un paragraphe, ils doivent être séparés par une ligne contenant un seul signe dièse.

Voici un exemple de commentaire en bloc qui définit ce qui se passe dans la fonction main() définie ci-dessous :

# The main function will parse arguments via the parser variable.  These
# arguments will be defined by the user on the console.  This will pass
# the word argument the user wants to parse along with the filename the
# user wants to use, and also provide help text if the user does not
# correctly pass the arguments.

def main():
  parser = argparse.ArgumentParser()
  parser.add_argument(
      "word",
      help="the word to be searched for in the text file."
  )
  parser.add_argument(
      "filename",
      help="the path to the text file to be searched through"
  )
...

Les commentaires en bloc sont généralement utilisés lorsque les opérations sont moins compréhensibles et nécessitent donc une explication détaillée. Vous devriez essayer d'éviter de sur-commenter le code et devriez avoir tendance à faire confiance aux autres programmeurs pour comprendre Python, sauf si vous écrivez pour un public particulier.

Commentaires en ligne

Les commentaires en ligne se produisent sur la même ligne qu'une instruction, suivant le code lui-même. Comme les autres commentaires, ils commencent par un signe dièse et un seul caractère d'espace.

En général, les commentaires en ligne ressemblent à ceci :

[code]  # Inline comment about the code

Les commentaires en ligne doivent être utilisés avec parcimonie, mais peuvent être efficaces pour expliquer des parties du code difficiles ou complexes. Ils peuvent également être utiles si vous pensez que vous pourriez ne pas vous souvenir d'une ligne du code que vous écrivez à l'avenir, ou si vous collaborez avec quelqu'un qui, vous le savez, peut ne pas être familier avec tous les aspects du code.

Par exemple, si vous n’utilisez pas beaucoup de mathématiques dans vos programmes Python, vous ou vos collaborateurs pourriez ne pas savoir que ce qui suit crée un nombre complexe, vous pourriez donc vouloir inclure un commentaire en ligne à ce sujet :

z = 2.5 + 3j  # Create a complex number

Les commentaires en ligne peuvent également être utilisés pour expliquer la raison de faire quelque chose, ou certaines informations supplémentaires, comme dans :

x = 8  # Initialize x with an arbitrary number

Les commentaires faits en ligne ne doivent être utilisés que lorsque c'est nécessaire et lorsqu'ils peuvent fournir des conseils utiles à la personne qui lit le programme.

Commenter le code pour les tests

En plus d’utiliser les commentaires comme moyen de documenter le code, le signe dièse peut également être utilisé pour commenter du code que vous ne souhaitez pas exécuter pendant que vous testez ou déboguez un programme que vous êtes en train de créer. C’est-à-dire que lorsque vous rencontrez des erreurs après avoir implémenté de nouvelles lignes de code, vous pouvez vouloir en commenter quelques-unes pour voir si vous pouvez identifier le problème précis.

Utiliser le symbole dièse peut également vous permettre d'essayer des alternatives pendant que vous déterminez comment configurer votre code. Par exemple, vous pouvez être en train de décider entre utiliser une boucle while ou une boucle for dans un jeu Python, et pouvez commenter l'une ou l'autre tout en testant et en déterminant laquelle pourrait être la meilleure :

import random

number = random.randint(1, 25)

# number_of_guesses = 0

for i in range(5):
# while number_of_guesses < 5:
    print('Guess a number between 1 and 25:')
    guess = input()
    guess = int(guess)

    # number_of_guesses = number_of_guesses + 1

    if guess < number:
        print('Your guess is too low')

    if guess > number:
        print('Your guess is too high')

    if guess == number:
        break

if guess == number:
    print('You guessed the number!')

else:
    print('You did not guess the number. The number was ' + str(number))

Commenter du code avec le signe dièse peut vous permettre d'essayer différentes méthodes de programmation ainsi que de vous aider à trouver la source d'une erreur en commentant et en exécutant systématiquement des parties d'un programme.

Conclusion

Utiliser des commentaires dans vos programmes Python aide à rendre vos programmes plus lisibles pour les humains, y compris vous-même dans le futur. Inclure des commentaires appropriés, pertinents et utiles peut faciliter la collaboration avec d'autres sur des projets de programmation et rendre la valeur de votre code plus claire.

À partir d'ici, vous pouvez vouloir lire à propos des Docstrings de Python dans PEP 257 pour vous fournir plus de ressources afin de documenter correctement vos projets Python.