Commenter du code source avec l'IA

Bonjour, l’intelligence artificielle a connu des avancées significatives, notamment dans le domaine de la génération automatique de scripts et de programmes informatiques. Cependant, elle n’a pas encore atteint la capacité de se substituer totalement à un développeur logiciel expérimenté. En revanche, pour l’ensemble des utilisateurs, qu’ils soient débutants, intermédiaires ou avancés, l’IA peut s’avérer extrêmement utile pour automatiser des tâches mineures mais fastidieuses, telles que la génération de commentaires dans un code dépourvu de leurs annotations.

Dans le contexte de la programmation, notamment avec le langage AutoLISP, il est fréquent de rencontrer des programmes récupérés sur Internet qui manquent de documentation ou comportent peu de commentaires, rendant leur compréhension difficile. L’intelligence artificielle peut alors aisément générer des commentaires explicatifs pour ces segments de code. À titre d’exemple, prenons un programme autonome fourni dans une documentation Autodesk®, que voici:

(defun c:makepoly ( / points pt)
  (setq points '())
  (prompt "\nCliquez des points pour la polyligne (appuyez sur Entrée pour terminer)")
  (while (setq pt (getpoint "\nPoint suivant : "))
    (setq points (append points (list pt)))
  )
  (if (>= (length points) 3)
    (progn
      (entmakex
        (append
          (list (cons 0 "LWPOLYLINE")
                (cons 100 "AcDbEntity")
                (cons 100 "AcDbPolyline")
                (cons 70 1))  ; 1 = fermé
          (mapcar '(lambda (p i) (cons (list 10 (car p) (cadr p)) i))
                  points
                  (number-sequence 0 (1- (length points))))
        )
      )
      (prompt "\nPolyligne fermée créée.")
    )
    (prompt "\nAu moins 3 points sont nécessaires pour créer une polyligne fermée.")
  )
  (princ)
)

Nous sollicitons ici une IA, en l’occurrence le modèle Gemini de Google, en mode génération de code, afin d’enrichir ce programme avec des commentaires explicatifs. Le résultat obtenu s’affiche ci-après:

;; =====================================================================
;; Programme AutoLISP : c:makepoly
;;
;; Description :
;; Ce programme permet à l'utilisateur de créer une polyligne fermée 
;; dans AutoCAD en cliquant successivement sur au moins trois points 
;; dans le dessin. L'utilisateur démarre la commande, clique des points, 
;; et lorsqu'il appuie sur Entrée (sans sélectionner de point), 
;; le programme vérifie si au moins trois points ont été donnés.
;;
;; Si oui, il génère une polyligne fermée (LWPOLYLINE) avec ces sommets.
;; Sinon, il affiche un message d'erreur signalant qu'au moins trois 
;; points sont nécessaires.
;;
;; Résumé des fonctionnalités :
;; - Collecte interactive de points via clic utilisateur.
;; - Vérification du nombre minimum de points requis (≥ 3).
;; - Création automatique d'une polyligne fermée dans le dessin courant.
;; - Messages d’information affichés pour guider l’utilisateur.
;;
;; Auteur : (à compléter)
;; Date   : (à compléter)
;; =====================================================================
(defun c:makepoly ( / points pt)
  ;; Initialise une liste vide pour stocker les points cliqués par l'utilisateur
  (setq points '())  
  
  ;; Affiche un message demandant à l'utilisateur de cliquer des points
  ;; L'utilisateur peut appuyer sur Entrée pour finir
  (prompt "\nCliquez des points pour la polyligne (appuyez sur Entrée pour terminer)")
  
  ;; Boucle qui continue tant que l'utilisateur fournit un point avec la souris
  (while (setq pt (getpoint "\nPoint suivant : "))
    ;; Ajoute le point sélectionné à la liste des points existants
    (setq points (append points (list pt)))
  )
  
  ;; Vérifie si le nombre de points est suffisant (au moins 3) pour créer une forme fermée
  (if (>= (length points) 3)
    (progn
      ;; Crée une entité graphique dans le dessin (ici, une polyligne légère fermée)
      (entmakex
        (append
          (list (cons 0 "LWPOLYLINE")       ;; Définit le type d'entité : polyligne légère (optimisée)
                (cons 100 "AcDbEntity")     ;; Spécifie qu'il s'agit d'une entité AutoCAD
                (cons 100 "AcDbPolyline")   ;; Spécifie la sous-classe de l'entité (polyligne)
                (cons 70 1))                ;; Drapeau : 1 signifie que la polyligne est fermée
          
          ;; Ajoute les sommets (vertices) de la polyligne :
          ;; mapcar applique une fonction à chaque élément de la liste 'points'
          ;; La fonction ici crée un couple ((10 x y) . i) pour chaque point,
          ;; où (10 x y) définit les coordonnées du sommet,
          ;; et i est l’index (non utilisé directement ici, mais inclus par la logique).
          (mapcar '(lambda (p i) 
                     ;; Crée une paire (cons) où 10 désigne un point de la polyligne,
                     ;; suivi de ses coordonnées X et Y
                     (cons (list 10 (car p) (cadr p)) i))
                  points
                  ;; Génère une liste d'index de 0 à (n-1), utilisée pour accompagner chaque point
                  (number-sequence 0 (1- (length points))))
        )
      )
      ;; Message de confirmation à l'utilisateur que la polyligne a été créée
      (prompt "\nPolyligne fermée créée.")
    )
    ;; Si moins de 3 points sont donnés, affiche un message d'erreur
    (prompt "\nAu moins 3 points sont nécessaires pour créer une polyligne fermée.")
  )
  
  ;; Termine proprement la commande AutoLISP en retournant nil (pas de valeur affichée dans la console)
  (princ)
)

C’est bien joli tout ça, mais le principe du commentaire n’est pas d’expliquer ce que fait une fonction, mais de décrire pourquoi le développeur a fait ceci ou cela et permettre à lui-même ou à la personne suivante qui fera la maintenance du code de comprendre l’algorithme et les choix sous-jacents.
Par exemple, ce commentaire ne sert à rien
;; Vérifie si le nombre de points est suffisant (au moins 3) pour créer une forme fermée
(if (>= (length points) 3)
Par contre le fait que la fonction number-sequence n’existe pas et rende ce lisp inutilisable aurait été plus intéressante à diagnostiquer :wink: mais visiblement, l’IA l’a commenté sans que ça lui pose de problème.

2 « J'aime »

Bonjour Olivier,

Je te remercie pour tes commentaires. Il est effectivement essentiel que le code informatique soit documenté dès sa conception, et non a posteriori. Cette documentation doit obligatoirement être réalisée par la ou les personnes qui ont écrit le code initial, ce sur quoi nous sommes pleinement d’accord.

Cependant, comme tu le sais, la majorité des routines disponibles en ligne, notamment AutoLISP réalisées par des amateurs, sont souvent peu ou pas du tout documentées. J’ai donc pris la liberté de me placer dans la position d’un utilisateur plutôt débutant souhaitant comprendre un minimum le fonctionnement du programme, ainsi que certaines fonctions AutoLISP.

C’est la raison pour laquelle certaines fonctions sont explicitement expliquées dans le code, notamment par l’intermédiaire de la documentation fournie par l’Intelligence Artificielle, qui a été sollicitée pour rédiger des commentaires en se mettant à la place d’un utilisateur débutant, afin de faciliter la compréhension.

Concernant la fonction qui n’est pas définie dans ce code : je précise que je n’ai pas personnellement essayé d’exécuter ce programme. La première raison est que je ne possède plus AutoCAD®. La seconde, c’est que ce code provient d’un fichier d’aide d’Autodesk®, et je suppose qu’il fonctionnait, puisque je l’ai récupéré quelque part, bien que je ne me souvienne plus précisément où. Il est probable qu’il s’agissait d’un extrait parmi plusieurs, et qu’une autre partie du fichier définit la fonction absente dans cet extrait, ce qui expliquerait cette situation.

Enfin, ma demande n’était pas de procéder au débogage du code, ce qui relève d’un travail spécifique généralement effectué avec des outils appropriés. Nous en avons d’ailleurs longuement discuté dans la section consacrée à l’intelligence artificielle et à la programmation sur ce site.

Si on veut déboguer le code il faut le demander dans le prompt et comme suit, un dialogue avec l’IA s’engage (je ne vais pas plus loin, je n’ai aucun moyen de tester et ce n’était pas le but de cet article):

Réponse de l’IA:
Je vois le problème dans votre code AutoLISP ! La fonction number-sequence n’existe pas en AutoLISP. Cette fonction semble venir d’Emacs Lisp.

Voici les problèmes principaux et la correction :

Problèmes identifiés :

  1. number-sequence n’existe pas en AutoLISP
  2. La structure des codes DXF pour LWPOLYLINE n’est pas correcte
  3. La façon de construire les sommets de la polyligne n’est pas appropriée

Version corrigée :

(defun c:makepoly ( / points pt vertex-list)
  (setq points '())
  (prompt "\nCliquez des points pour la polyligne (appuyez sur Entrée pour terminer)")
  
  ; Collecte des points
  (while (setq pt (getpoint "\nPoint suivant : "))
    (setq points (append points (list pt)))
  )
  
  ; Vérification du nombre minimum de points
  (if (>= (length points) 3)
    (progn
      ; Construction de la liste des sommets
      (setq vertex-list '())
      (foreach point points
        (setq vertex-list 
          (append vertex-list 
            (list (cons 10 (list (car point) (cadr point))))
          )
        )
      )
      
      ; Création de la polyligne
      (entmakex
        (append
          (list 
            (cons 0 "LWPOLYLINE")
            (cons 100 "AcDbEntity")
            (cons 100 "AcDbPolyline")
            (cons 90 (length points))  ; Nombre de sommets
            (cons 70 1)               ; 1 = fermé
          )
          vertex-list
        )
      )
      (prompt "\nPolyligne fermée créée.")
    )
    (prompt "\nAu moins 3 points sont nécessaires pour créer une polyligne fermée.")
  )
  (princ)
)

Principales corrections :

  1. Suppression de number-sequence : Remplacé par une boucle foreach
  2. Code DXF 90 : Ajout du nombre de sommets (obligatoire pour LWPOLYLINE)
  3. Structure des sommets : Correction de la façon dont les coordonnées sont assignées
  4. Simplification : Code plus lisible et plus conforme aux standards AutoLISP

Cette version devrait fonctionner correctement dans AutoCAD® !

Patrick,

Merci d’avoir précisé le contexte en indiquant que ça s’adressait à des développeurs débutant qui souhaitent apprendre le langage.
Malgré tout, j’insiste sur le fait que le commentaire n’a aucun intérêt s’il décrit ce que fait une fonction basique.
Par exemple en face d’une ligne (getreal… écrire un commentaire qui dit « Demande la saisie d’un nombre réel à l’utilisateur » est totalement inutile.
Si je reprends l’un des commentaires

; Vérification du nombre minimum de points
  (if (>= (length points) 3)

Le vrai commentaire intéressant serait de savoir pourquoi 3 points au minimum.
En effet, AutoCAD® autorise de créer des polylignes fermées à 2 points (la commande ANNEAU crée une polyligne à 2 points fermée et n’exige pas 3 points minimum).
Donc peut-être que la raison est 20 ou 100 lignes plus loin, car il faut qu’il y ait absolument 3 points pour X ou Y raison… Ca c’est utile, sinon aucun intérêt.

Maintenant, si ça permet à un débutant de mieux comprendre ce que fait une routine dénichée sur internet, fonction après fonction, alors pourquoi pas, mais pour moi ça reste superflu pour qui cherche vraiment à apprendre et à comprendre comment fonctionne un programme informatique.
Je suis sûrement trop vieux, mais pour moi, apprendre à coder, en récupérant un programme tout fait et en demandant à une IA de me la commenter, n’est pas la bonne manière de faire ni d’apprendre.

Je ne dis pas non plus que c’est la façon d’apprendre à programmer. Je ne l’ai mentionné nulle part dans cette conversation, d’ailleurs. Tu le sais déjà : beaucoup de débutants récupèrent plein de routines écrites en langage Lisp, qui circulent sur Internet depuis des années. Ils essaient de les faire fonctionner ou même de les adapter à leurs besoins, sans vraiment comprendre comment elles fonctionnent ou sans connaître du tout l’automatisme ou la logique qui se cache derrière. C’est quelque chose de très courant, et on voit ça souvent sur les forums d’entraide. Il est évident que les commentaires ajoutés par une intelligence artificielle dans cet extrait de code, pris comme exemple, ne sont pas très utiles pour un programmeur qui a un peu d’expérience.