# 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 :**

```python
# 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
```

{% hint style="info" %}
La compilation (ou l'interprétation) est une étape effectuée par les langages de programmation avant l'exécution du programme.
{% endhint %}

## 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

```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.

```python
# 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

<figure><img src="https://700524925-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn5YnWU89G98lz0ROIcGu%2Fuploads%2FQkvAU59X0wM2ttgpbfX7%2FExempleTODO.png?alt=media&#x26;token=8922645e-23cd-4f08-9537-fa1a83ab3730" alt=""><figcaption></figcaption></figure>

## 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 :**&#x20;
  * `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**&#x20;
  * **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.**
