Ces commentaires qui en disent trop long

Il existe un genre de commentaire qui pullule dans les bases de code assistées par IA. Vous savez desquels je parle :

# Maintenant on utilise une dictionary comprehension comme demandé
user_emails = {user.id: user.email for user in users}

# Corrigé le bug dont on a parlé concernant la gestion des nulls
if data and data.get('value'):
    process(data['value'])

Ces commentaires n'expliquent pas le code. Ils racontent la conversation. Et c'est là que ça pose problème.

Pourquoi les « fuites de prompt » sont un code smell

Quand un commentaire décrit ce que le développeur a demandé à l'IA de faire plutôt que ce que le code accomplit réellement, ça crée plusieurs complications :

1. Confusion temporelle Le commentaire s'adresse à un lecteur qui aurait été présent pendant le développement. « Maintenant on utilise... » sous-entend que quelqu'un a vu l'état d'avant. Les futurs mainteneurs—including future-you—n'auront pas ce contexte.

2. Documentation qui pourrit Les commentaires ancrés au prompt deviennent obsolètes dès que les besoins évoluent. Si les exigences changent, ces commentaires induisent activement en erreur sur la raison d'être du code.

3. Bruit plutôt que signal Un bon commentaire explique le pourquoi, pas le quoi. Le code montre déjà ce qu'il fait. Les commentaires doivent éclairer l'intention, les contraintes et le contexte qui ne sont pas évidents à la lecture.

Le test : est-ce qu'un Martien comprendrait ?

Voici un diagnostic simple : est-ce qu'une personne ignorant tout de votre processus de développement pourrait comprendre ce commentaire ?

Mauvais commentaire :

# Remplacé la boucle for par une list comprehension pour l'efficacité
results = [transform(x) for x in data]

Bon commentaire :

# La list comprehension surpasse la boucle pour les gros volumes grâce à l'optimisation de l'interpréteur
results = [transform(x) for x in data]

La bonne version explique pourquoi cette approche a été choisie. Elle reste utile même des années après.

Ce dont le code « vibe » a vraiment besoin

Le vibe coding — ce développement assisté par IA qui privilégie la livraison à la perfection — a une valeur réelle. La vitesse compte. Mais la vélocité ne doit pas se faire au détriment de la maintenabilité.

Quand votre assistant IA suggère un commentaire, posez-vous ces questions :

• Est-ce que ça explique pourquoi ce code existe ?
• Est-ce que ça aurait du sens pour quelqu'un qui le lirait dans deux ans ?
• Est-ce qu'on documente le but du code ou le processus de développement ?

Si c'est la deuxième option, supprimez-le. Votre futur vous vous en sera reconnaissant.

Construire de meilleures habitudes de collaboration avec l'IA

La solution n'est pas de arrêter d'utiliser les assistants IA — c'est de développer de meilleures pratiques de relecture :

1. Lisez les commentaires avant de les accepter. Est-ce que le commentaire ajoute de la valeur ou raconte juste la conversation de développement ?

2. Réécrivez les commentaires générés par l'IA. Mieux : écrivez les vôtres. Vous connaissez le contexte métier que l'IA ne connaît pas.

3. Établissez des standards d'équipe. Si des commentaires pareils passent à travers les revues de code, la qualité de votre codebase va graduellement se dégrader.

4. Privilégiez le code auto-documenté. Un naming clair, une bonne structure et des abstractions appropriées éliminent souvent le besoin de commentaires.

Le mot de la fin

On lit le code bien plus souvent qu'on l'écrit. Les commentaires qui documentent le prompt plutôt que le propósito créent une dette technique qui s'accumule avec le temps. Dans la précipitation pour livrer, c'est tentant de laisser passer ça — mais c'est une forme de dette technique qui induit activement en erreur les développeurs futurs.

Les meilleures bases de code racontent une histoire. Les commentaires doivent expliquer l'intrigue, pas les notes du scénariste.

Chez NameOcean, on croit que les bonnes pratiques de développement vont bien au-delà du simple hébergement. Que vous codiez en mode vibe votre MVP ou que vous architecturiez des systèmes enterprise, les fondamentaux d'un code propre et maintenable restent essentiels. Votre domain est votre identité digitale — autant s'assurer que le code derrière reflète bien ce que vous êtes.