Comment écrire des commentaires de code qui guident un assistant de programmation IA?

GitHub Copilot, le programmeur en binôme IA qui fonctionne dans des éditeurs comme Visual Studio Code, suggère du code pendant que vous tapez. Il lit ce qui se trouve déjà dans votre fichier, y compris les commentaires, et prédit ce qui devrait venir ensuite. Le guide de démarrage de GitHub montre la version la plus simple : tapez un commentaire en anglais courant, et Copilot propose du code qui fait ce que le commentaire décrit.

Vos commentaires deviennent donc une sorte de prompt. Un commentaire vague obtient une supposition plausible. Un commentaire précis obtient quelque chose de beaucoup plus proche de ce dont vous avez besoin. Une façon pratique de travailler est le développement guidé par la docstring : avant d’écrire une fonction, vous rédigez sa docstring, la description placée en tête d’une fonction en Python, comme si vous expliquiez la tâche à un collègue attentif. Ensuite, vous laissez l’assistant rédiger le corps de la fonction et vous le vérifiez par rapport à ce que vous avez écrit.

Pourquoi le commentaire compte autant

Copilot repose sur une version de Codex d’OpenAI, un modèle GPT entraîné sur du code public de GitHub. L’article de recherche sur Codex l’a évalué d’une façon qui correspond parfaitement à cette habitude. Son banc d’essai, appelé HumanEval, donne au modèle la signature d’une fonction et une docstring, puis exécute des tests unitaires sur le code qu’il écrit. Autrement dit, les chercheurs ont mesuré à quel point Codex transforme bien une docstring en code fonctionnel.

L’article a aussi relevé une faiblesse nette. Plus une docstring décrit d’étapes enchaînées, plus le taux de réussite de Codex chute fortement, d’un facteur de deux ou trois pour chaque étape supplémentaire. La leçon pour l’usage quotidien : décrivez une seule tâche par fonction, et découpez les longs traitements en plusieurs petites fonctions, chacune avec sa courte docstring.

Un exemple concret : avant et après

Supposons que vous deviez nettoyer des numéros de téléphone saisis dans un formulaire d’inscription.

Avant : un commentaire vague.

# nettoyer le numéro de téléphone
def clean_phone(s):

Copilot ne peut que deviner. Il pourrait retirer les espaces, ou supprimer tout ce qui n’est pas un chiffre, ou ajouter un indicatif de pays. N’importe laquelle de ces options pourrait être la bonne, et le commentaire ne vous permet pas de savoir laquelle vous vouliez.

Après : une docstring rédigée comme une spécification.

def clean_phone(raw: str) -> str:
    """Normalise un numéro de téléphone nord-américain sous la forme 555-123-4567.

    Accepte des chiffres avec n’importe quel mélange d'espaces, de points, de tirets et de parenthèses.
    Un indicatif de pays 1 ou +1 en tête est accepté et retiré.
    Lève ValueError si le résultat ne compte pas exactement 10 chiffres.

    Exemples :
        clean_phone("(613) 555-0199")   -> "613-555-0199"
        clean_phone("+1 613.555.0199")  -> "613-555-0199"
        clean_phone("555-0199")         -> ValueError
    """

L’assistant connaît maintenant l’entrée, le format de sortie, le préfixe facultatif, le cas d’erreur et trois exemples concrets. Les annotations de type (str en entrée, str en sortie) ajoutent encore de l’information. La suggestion obtenue a beaucoup plus de chances de correspondre, et les exemples servent aussi de liste de contrôle : exécutez chacun d’eux et voyez si le code se comporte comme promis.

Voici ce qui a changé entre les deux versions :

Quelques autres habitudes aident. Placez le commentaire juste au-dessus de l’endroit où le code doit commencer, pour que ce soit la dernière chose que le modèle lit. Employez les mêmes mots que votre code : si une variable s’appelle invoice_total, ne l’appelez pas « le montant » dans le commentaire. Et si la première suggestion rate la cible, regardez les autres; dans VS Code, Ctrl+Entrée ouvre un panneau qui présente plusieurs options.

Ce que les commentaires ne peuvent pas faire

Une bonne docstring augmente les chances d’obtenir une suggestion utile, mais elle ne garantit pas un code correct. GitHub précise que Copilot n’exécute ni ne teste ce qu’il écrit, que ses suggestions peuvent ne pas fonctionner et qu’il peut reproduire des pratiques non sécuritaires trouvées dans du code public. La spécification est précieuse justement parce qu’elle vous donne un point de comparaison pour vérifier la suggestion.

Comment garder ses suggestions cohérentes avec votre projet?

Copilot copie les régularités qu’il peut voir. GitHub a expliqué qu’il tire son contexte surtout du fichier que vous modifiez et que, dans les longs fichiers, seules les quelques centaines de lignes précédentes sont utilisées. La façon la plus fiable de garder les suggestions dans le style de votre projet est donc de rendre ce style visible près de l’endroit où vous travaillez.

En pratique, cela veut dire quelques gestes. Gardez vos importations en haut du fichier, pour que Copilot se tourne vers les bibliothèques que vous utilisez déjà plutôt que vers d’autres. Écrivez une fonction à la main dans votre style préféré, avec vos noms, votre gestion des erreurs et votre journalisation, et placez les nouvelles fonctions après elle; l’assistant a tendance à suivre l’exemple. Utilisez des annotations de type et des noms cohérents, parce qu’ils répètent les mêmes signaux à chaque ligne. Si votre projet a des fonctions utilitaires pour les dates, l’argent ou l’accès à la base de données, nommez-les dans la docstring (« utilise parse_iso_date de utils ») pour que la suggestion appelle votre fonction au lieu d’en écrire une nouvelle.

Enfin, gardez vos protections habituelles. Un linter et un formateur, des outils qui vérifient et mettent en forme le code automatiquement, repéreront les écarts de style. Vos tests existants repéreront les écarts de comportement. Relire chaque suggestion comme si elle venait d’un nouveau coéquipier garde le code bien à vous.