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'inclusion de commentaires dans les programmes rend le code plus lisible pour les humains car il fournit des informations ou des explications sur ce que fait chaque partie d'un programme.
En fonction de l'objectif de votre programme, les commentaires peuvent vous servir de notes 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, c'est une bonne idée d'écrire des commentaires pendant que vous écrivez ou mettez à jour un programme, car il est facile d'oublier votre processus de pensée plus tard, et les commentaires écrits plus tard peuvent être moins utiles à long terme.
Les commentaires en Python commencent par une marque de hachage (#) et un caractère d'espacement et continuent jusqu'à la fin de la ligne.
Généralement, les commentaires ressemblent à ceci:
# This is a commentComme les commentaires ne s'exécutent pas, vous ne verrez aucune indication du commentaire lorsque vous exécuterez un programme. Les commentaires sont dans le code source pour les humains à lire, pas pour les ordinateurs à exécuter.
Dans un programme «Hello, World!», Un commentaire peut ressembler à ceci:
hello.py
# Print “Hello, World!” to console
print("Hello, World!")sharks.py
# 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 avec le même retrait que le code qu’il commente. Autrement dit, unfunction definition sans retrait aurait un commentaire sans retrait, et chaque niveau d'indentation suivant aurait des commentaires alignés avec le code qu'il commente.
Par exemple, voici comment la fonctionagain() duHow To Make a Simple Calculator Program in Python 3 tutorial est commentée, avec des commentaires après chaque niveau d'indentation du code:
calculator.py
...
# 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, que ce soit le programmeur d'origine ou une autre personne utilisant ou collaborant dans le projet. Si les commentaires ne peuvent pas être correctement gérés et mis à jour avec la base de code, il est préférable de 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 auxwhy derrière le code par opposition auxwhat ouhow. À moins que le code ne soit particulièrement délicat, le regarder peut généralement indiquer ce que fait le code ou comment il le fait.
Les commentaires de blocage peuvent être utilisés pour expliquer un code plus complexe ou un code que le lecteur ne devrait pas connaître. Ces commentaires plus longs s'appliquent à tout ou partie du code qui suit et sont également mis en retrait au même niveau que le code.
Dans les commentaires de bloc, chaque ligne commence par le signe dièse et un seul espace. Si vous devez utiliser plusieurs paragraphes, ils doivent être séparés par une ligne contenant un seul signe de hachage.
Voici un exemple de commentaire de bloc qui définit ce qui se passe dans la fonctionmain() 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 de bloc sont généralement utilisés lorsque les opérations sont moins simples et exigent par conséquent une explication approfondie. Vous devriez essayer d'éviter de trop commenter le code et devriez avoir tendance à faire confiance aux autres programmeurs pour comprendre Python, sauf si vous écrivez pour un public particulier.
Les commentaires en ligne apparaissent sur la même ligne d'une instruction, à la suite du code lui-même. Comme d'autres commentaires, ils commencent par un signe dièse et un seul caractère d'espacement.
Généralement, les commentaires en ligne ressemblent à ceci:
[code] # Inline comment about the codeLes commentaires en ligne doivent être utilisés avec parcimonie, mais ils peuvent être efficaces pour expliquer des parties de code difficiles ou non évidentes. Ils peuvent également être utiles si vous pensez ne pas vous souvenir d’une ligne du code que vous écrivez à l’avenir ou si vous collaborez avec une personne que vous connaissez ne connaissez peut-être pas tous les aspects du code.
Par exemple, si vous n'utilisez pas beaucoup demath dans vos programmes Python, vous ou vos collaborateurs pouvez ne pas savoir que ce qui suit crée un nombre complexe, vous pouvez donc inclure un commentaire en ligne à ce sujet:
z = 2.5 + 3j # Create a complex numberLes commentaires en ligne peuvent également être utilisés pour expliquer la raison de faire quelque chose ou des informations supplémentaires, comme dans:
x = 8 # Initialize x with an arbitrary numberLes commentaires formulés en ligne ne doivent être utilisés que lorsque cela est nécessaire et qu'ils peuvent fournir des indications utiles à la personne qui lit le programme.
En plus d’utiliser les commentaires pour documenter le code, la marque de hachage peut également être utilisée pour commenter le code que vous ne voulez pas exécuter pendant que vous testez ou déboguez un programme que vous créez actuellement. C'est-à-dire que lorsque vous rencontrez des erreurs après avoir implémenté de nouvelles lignes de code, vous pouvez en commenter quelques-unes pour voir si vous pouvez résoudre le problème en question.
L'utilisation de la marque de hachage peut également vous permettre d'essayer des alternatives tout en déterminant comment configurer votre code. Par exemple, vous pouvez décider d'utiliser une bouclewhile loop oufor dans un jeu Python, et pouvez commenter l'un ou l'autre tout en testant et en déterminant laquelle peut être la meilleure:
guess.py
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))La mise en commentaire du code avec la marque de hachage peut vous permettre d'essayer différentes méthodes de programmation et vous aider à trouver la source d'une erreur en commentant et en exécutant systématiquement des parties d'un programme.
Conclusion
L'utilisation de commentaires dans vos programmes Python contribue à améliorer la lisibilité de vos programmes pour les humains, y compris pour votre avenir. L'inclusion de commentaires appropriés, pertinents et utiles, peut faciliter la collaboration d'autres personnes avec vous sur des projets de programmation et rendre la valeur de votre code plus évidente.
À partir de là, vous pouvez consulter lesDocstrings in PEP 257 de Python pour vous fournir plus de ressources pour documenter correctement vos projets Python.