Recommandations à propos des commentaires dans les programmes

Voici quelques recommandations sur l'écriture des commentaires dans les programmes assembleurs à remettre dans le cadre des travaux pratiques du cours. Ce sont ces critères qui seront utilisés pour évaluer la qualité de vos commentaires.

Un commentaire dans un programme a comme but ultime de rendre plus compréhensible les instructions du code. Il n'a pas comme objectif d'expliquer l'algorithme. (L'algorithme devrait être expliqué ailleurs.)

L'erreur la plus répandue est de simplement décrire ce que fait l'instruction, e.g. move.w #0,d0 ; mettre zéro dans d0. Ce type de commentaire a très peu d'utilité, pour ne pas dire qu'il est complètement inutile. Toute personne qui connaît quelque peu l'assembleur sait que cette instruction place zéro dans le registre d0. Je parie même que le premier venu le saura.

Il est vrai qu'on pourra trouver de tels commentaires dans certains programmes dont le but est d'expliquer le fonctionnement d'instructions. Mais c'est un cas particulier où la raison d'être des commentaires est centrée sur l'explication de l'usage de nouvelles instructions.

Un commentaire devrait expliquer pourquoi dans le contexte du problème cette instruction est utilisée. Par exemple, imaginons qu'un programme est écrit pour lire plusieurs nombres et faire leur somme. Un commentaire satisfaisant serait alors

move.w #0,d0 ; il y a zéro nombre lu

Dans ce dernier exemple, on peut alors percevoir que le registre d0 est utilisé pour compter les nombres lus.

Ainsi voici une règle importante:

Un commentaire ne doit pas décrire le fonctionnement d'une instruction mais devrait décrire dans le contexte du problème la raison de son usage.

L'usage de bons commentaires non seulement aide à comprendre l'utilisation de certaines instructions mais de plus, pour le correcteur de vos travaux, démontre que vous comprenez leur usage. De plus, une sous-routine devrait avoir un en-tête sous la forme de commentaires décrivant les paramètres d'entrée et la sortie. Peut-être que ces commentaires se réfèrent à un pseudo-code décrit ailleurs. Les paramètres sont les données qui sont fournies par l'appeleur de la sous-routine. La sortie est le résultat produit par la sous-routine.

Voici une sous-routine commentée sans contexte et les modifications apportées plus bas pour y remedier. Assurément, dans la première version, c'est une façon de NE PAS commenter un programme! Lisez attentivement la deuxième version et comparez avec la première. Dans la deuxième version il y a clairement des commentaires se référant au problème à résoudre, mais dans la première version. C'est la deuxième façon qui est la bonne!

Version 1. Voici une façon de NE PAS commenter le code assembleur.

; Entrée : a0 : pointe chaîne t 
;          a1 : pointe chaîne p (longueur > 0)
;          a2 : pointe chaîne s (même longueur que p)
;          (Les chaînes se terminent par nul.)
; Sortie : Modifie la chaîne de caractères t en substituant toutes les 
;          occurrences de la chaîne p par s.
;          (Note : les substitutions se font du début vers la fin de t)
;
subSPT:  movem.l a0-a4,-(sp)
chercheP:
         tst.b   (a0)+        ; teste octet
         beq     finT         ; branche à finT si zéro
         movea.l a1,a3        ; copie a1 dans a3
         lea     -1(a0),a4    ; 
compareP:
         tst.b   (a3)         ; teste un octet pointé par a3
         beq     Ptrouve      ; branche si zéro
         cmp.b   (a4)+,(a3)+  ; compare deux octets
         beq     compareP     ; branche si égaux
         bra     chercheP     ; 
Ptrouve: 
         movea.l a2,a4        ; copie a2 dans a4
         lea     (-1,a0),a0   ; 
remplaceP:                    ; 
         tst.b   (a4)         ; teste un octet
         beq     chercheP     ; branche si zéro à chercheP
         move.b  (a4)+,(a0)+  ; copie un octet
         bra     remplaceP    ; branche à remplaceP
finT:
         movem.l (sp)+,a0-a4
         rts

Version 2. Voici une façon de commenter le code assembleur.

; Entrée : a0 : pointe chaîne t 
;          a1 : pointe chaîne p (longueur > 0)
;          a2 : pointe chaîne s (même longueur que p)
;          (Les chaînes se terminent par nul.)
; Sortie : Modifie la chaîne de caractères t en substituant toutes les 
;          occurrences de la chaîne p par s.
;          (Note : les substitutions se font du début vers la fin de t)
;
subSPT:  movem.l a0-a4,-(sp)
chercheP:
         tst.b   (a0)+        ; fin de t ?
         beq     finT         ; oui, retour
         movea.l a1,a3        ; début de p
         lea     -1(a0),a4    ; position actuelle t[i]
compareP:
         tst.b   (a3)         ; est-ce la fin de p?
         beq     Ptrouve      ; oui, alors p est trouvée dans t
         cmp.b   (a4)+,(a3)+  ; t[i+j] = p[j] ?
         beq     compareP     ; oui, continue à comparer p[...] à t[i...]
         bra     chercheP     ; non, continue à chercher dans t
Ptrouve:                      ; une occurrence de p a été trouvée
         movea.l a2,a4        ; début s
         lea     (-1,a0),a0   ; début de p dans t
remplaceP:                    ; début remplace p par s dans t
         tst.b   (a4)         ; fin de s ?
         beq     chercheP     ; oui, copie terminée ; continue la recherche de p
         move.b  (a4)+,(a0)+  ; remplace un car. de p dans t par un car. de s
         bra     remplaceP
finT:
         movem.l (sp)+,a0-a4
         rts