Les commentaires

Les commentaires de base

Les commentaires sont des notes de texte ajoutées au programme pour fournir des informations explicatives pertinentes sur le code source. Ils ne sont pas exécutés, ils sont ignorés pendant la compilation ou l'interprétation du code.

Syntaxe Python : # Ceci est un commentaire

Exemples :

# Ceci est un commentaire expliquant ce que fait la prochaine ligne de code
total = sous_total + tax  # Ici, nous ajoutons la taxe au sous-total

La compilation (ou l'interprétation) est une étape effectuée par les langages de programmation avant l'exécution du programme.

Les commentaires multi-lignes

Ces commentaires peuvent couvrir plusieurs lignes. Ils sont entourés par trois guillemets doubles """ou trois apostrophes '''. Les commentaires multi-lignes sont couramment utilisés pour documenter des fonctions, des classes et des modules (que vous verrez dans d'autres cours) en fournissant des descriptions détaillées.

Exemple : documenter un fichier de code source en python

"""
Le code source de ce fichier permet de :
- Lire les notes des 3 examens des étudiants
- Calculer la moyenne
- Afficher la note finale aux étudiants 
"""

Les commentaires TODO

Vous pouvez avoir besoin d'écrire des commentaires que vous pourrez retrouver facilement plus tard afin de corriger ou finaliser votre code source.

# TODO: À déboguer plus tard

# TODO: Modifier la ligne suivante pour entrer des données lues de façon interactive

Allez dans PyCharm, et cliquez sur l'onglet TODO en bas de la fenêtre

Les bonnes pratiques lors de la rédaction des commentaires

• Prioriser la clarté du code avant la rédaction de commentaires.

• Prioriser la création de fonctions si vous devez commenter un bloc de code pour expliquer ce qu'il fait.

• Éviter les commentaires évidents. Exemples :

  • i = i + 1 # Incrémente i.

  • age = input("Veuillez entrer votre age : ") # lire l'âge de la personne.

• Exemples de cas où un commentaire serait pertinent

  • clarifier les parties complexes qui ne sont pas évidentes à comprendre et qu'il n'y a aucun moyen de le mettre en évidence via la clarté du code.

  • justifier un choix non intuitif dans le code.

• Ne pas oublier de mettre à jour les commentaires si le code source concerné change.