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
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:
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.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.
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!
; 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
; 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