Guide : Bien commenter son code

On apprend rarement à commenter, alors que c'est ce qui rend un code lisible… et ce que ton correcteur regardera. Ce guide rassemble toutes les règles. Chaque jour, le coin des commentaires de la fiche en travaille une.

---

1. Ce que ton prof attend

Le cahier des charges du projet est très clair : un code avec un commentaire à chaque ligne n'est pas un code valable. Les commentaires servent à décrire l'intention d'une portion de code, pas à réécrire le programme en français.

Autrement dit, ton correcteur pénalise autant le trop que le pas assez.

---

2. Le test du lecteur

Pour chaque commentaire, pose-toi une seule question :

Si je supprime ce commentaire, est-ce que quelqu'un qui connaît Python perd une information ?

• Non → le commentaire est inutile : supprime-le.
• Oui → garde-le, et vérifie qu'il est clair et juste.

x += speed * dt          # on ajoute speed fois dt à x

Ce commentaire ne survit pas au test : n'importe quel lecteur voit qu'on ajoute speed * dt à x.

x += speed * dt          # speed est en pixels par seconde, dt en secondes

Celui-ci survit : les unités ne se voient pas dans le code.

---

3. Les trois outils, du plus fort au plus faible

3.1 D'abord, les noms

Le meilleur commentaire est celui dont on n'a pas besoin, parce que le code se lit tout seul.

❌

def f(a, b, t):
    # calcule la position entre a et b
    return a + (b - a) * t

v = 3  # vitesse de la voiture

✅

def lerp(start, end, t):
    return start + (end - start) * t

car_speed = 3

Choisis des noms qui disent ce que c'est (frog, time_left, raft_under_frog) plutôt que des lettres ou des abréviations. Une fonction a un nom de verbe (create_cars, lose_life), une fonction qui répond à une question a un nom de question (is_jumping, is_on_screen).

3.2 Ensuite, les docstrings

Une docstring est un texte entre triples guillemets placé juste en dessous d'un def ou d'une class (ou tout en haut d'un fichier). Elle dit ce que fait la fonction ou ce que représente la classe, du point de vue de celui qui l'utilise.

def lane_positions(count: int, length: int) -> list:
    """Renvoie les positions x de count obstacles répartis sans chevauchement sur une voie."""
    ...


class Frog:
    """La grenouille du joueur, repérée en pixels et animée pendant ses sauts."""

À la différence d'un commentaire #, Python garde la docstring : ton éditeur l'affiche quand tu survoles la fonction, et help(lane_positions) l'affiche dans le terminal.

• Une phrase suffit la plupart du temps.
• Elle dit quoi, pas comment : « renvoie les positions », pas « fait une boucle sur count et tire un nombre au hasard ».
• Pas besoin de docstring pour une fonction évidente : draw(self, screen) ou is_jumping(self) se passent d'explication.

3.3 Enfin, les commentaires #

Un commentaire # explique ce que ni les noms ni la docstring ne peuvent dire : pourquoi le code est écrit comme ça.

# Les règles suivantes ne s'appliquent qu'une fois la grenouille posée
if self.frog.is_jumping():
    return

---

4. Quand un commentaire est utile

---

5. Quand un commentaire est nuisible

---

6. Le style

• Un dièse, une espace, puis une phrase : # Les maisons sont régulièrement espacées.
• Écris en français correct, avec une majuscule. Une seule langue pour tout le projet.
• Le commentaire d'un bloc se place au-dessus du bloc, au même niveau d'indentation.
• Le commentaire en fin de ligne est réservé aux courtes précisions (unités, valeur particulière) : TIME_LIMIT = 30 # secondes par grenouille.
• Reste court. Si un commentaire dépasse trois lignes, demande-toi si le code ne devrait pas être plus simple.

---

7. Un exemple complet, avant et après

❌ Avant : trop de commentaires, et pas les bons.

# fonction move
def move_obstacles(obstacles, dt):
    # boucle sur les obstacles
    for o in obstacles:
        # on bouge
        o[0] += o[3] * dt
        # si plus grand que 624
        if o[3] > 0 and o[0] > 624:
            # on remet à gauche
            o[0] = -o[2]
        # sinon si
        elif o[3] < 0 and o[0] + o[2] < 0:
            o[0] = 624  # à droite

✅ Après : de bons noms, des constantes, et un seul commentaire qui dit pourquoi.

def update(self, dt: float) -> None:
    self.x += self.speed * dt
    # Un obstacle sorti d'un côté réapparaît de l'autre, entièrement caché
    if self.speed > 0 and self.x > WIDTH:
        self.x = -self.width
    elif self.speed < 0 and self.x + self.width < 0:
        self.x = WIDTH

---

8. La checklist avant de rendre

• Chaque fichier commence par une phrase qui dit son rôle.
• Chaque classe a une phrase qui dit ce qu'elle représente.
• Chaque fonction ou méthode non évidente a une phrase qui dit ce qu'elle fait (pas comment).
• Les choix et les règles qui ne se voient pas dans le code sont expliqués (le pourquoi).
• Aucun commentaire ne répète le code.
• Aucun commentaire n'est faux ou périmé.
• Aucun code commenté, aucun print de débogage, aucun TODO.
• Pas de nombre magique : des constantes nommées.
• Les noms de variables, de fonctions et de classes sont assez clairs pour se passer de commentaires.
• Je sais expliquer chaque commentaire de mon code : le correcteur peut demander pourquoi il est là.