Leçon 5 : Raconter l'histoire du code : Commentaires et documentation efficaces

Les commentaires ne remplacent pas un code clair, mais ils sont essentiels pour clarifier une intention complexe, des décisions architecturales et la gestion des cas limites.

Le paradoxe du Vibe des commentaires

Si votre code nécessite des commentaires pour expliquer ce qu'il fait, c'est que le code lui-même manque de clarté (Mauvais Vibe). Les commentaires doivent expliquer pourquoi le code est écrit de cette manière (Bon Vibe).

Quand commenter (Bon Vibe)

1. Clarifier l'intention (Le pourquoi) : Expliquer un choix de conception non évident, en particulier les optimisations de performance ou les contournements pour des bibliothèques externes/bugs.
2. Résumés de haut niveau : Fournir une Docstring/Javadoc au début d'une fonction ou d'un module complexe pour décrire son but, ses entrées, ses sorties et ses effets secondaires.
3. Avertissements et TODOs : Marquer les zones qui nécessitent une attention future (TODO: Refactoriser ceci dans un service dédié plus tard.).

python

Commentaire Bon Vibe : Expliquer le « pourquoi » architectural

ATTENTION : Ce hack est nécessaire car l'API héritée (V1) renvoie l'heure

dans le fuseau horaire local, violant la pratique standard UTC. À supprimer quand la V2 sera en ligne.

timestamp = adjust_for_legacy_tz(response['time'])

Quand NE PAS commenter (Mauvais Vibe)

Évitez de commenter l'évidence. Ces commentaires encombrent le code et ajoutent du bruit visuel.

javascript // Mauvais Vibe : Commentaire évident // Boucle à travers la liste des utilisateurs for (let i = 0; i < users.length; i++) { // Incrémenter le compteur de 1 count++; }

Vibe de la documentation (externe)

Le Vibe Coding s'étend au-delà du fichier. Assurez-vous que votre documentation au niveau du module (Readmes, docs API) est facile à trouver et à utiliser. Un développeur devrait pouvoir cloner votre dépôt et commencer sans avoir à lire dans vos pensées.