Création d'un guide de style de code
Publié le 20 octobre 2022 par Andrew Owen (6 minutes)
J’ai déjà écrit sur l’importance d’un guide de style pour le contenu écrit. Il en va de même pour le code. On peut même dire que c’est encore plus important parce que le code est beaucoup plus difficile à comprendre. En ce qui concerne le style du code, vous ne trouverez jamais deux développeurs qui soient d’accord sur tout. Mon conseil serait donc de demander l’avis de tous ceux qui touchent au code et de parvenir à un consensus sur le style à adopter. N’oubliez pas qu’il s’agit d’un guide et non d’un ensemble de règles rigides.
Comme j’ai passé près de 15 ans à travailler comme rédacteur technique, la plupart des codages que j’ai effectués dans ma vie l’ont été pour mon propre amusement. Cela signifie que j’ai été libre de faire ce que je voulais. Mais pendant cette période, j’ai pris quelques mauvaises habitudes que j’ai essayé d’éviter. En particulier, j’ai eu affaire à beaucoup de code source en langage d’assemblage Z80. La plupart d’entre eux sont horribles. Mes griefs sont les suivants:
Mon propre style de code est essentiellement une réaction contre cela. J’ai également été influencé par un document publié par Nikos Drakos et Ken Clowes à la Computer Based Learning Unit de l’Université de Leeds, et par le fait que j’ai eu l’habitude d’écrire de la documentation SDK pour les développeurs C++. Je vais maintenant tenter de le documenter formellement. À l’avenir, je devrais l’étendre. En cas d’information manquante, je m’en remets à l’avis de l’auteur de l’article C++ Core Guidelines.
Ce document décrit les normes de codage pour les programmes en langage d’assemblage Z80. Les plug-ins suivants sont recommandés pour Visual Studio Code:
Si vous utilisez quelque chose de plus moderne que le Z80, je vous recommande également ces plug-ins:
Les appels à l’API doivent utiliser une table de vecteurs afin que la relocalisation du code cible ne perturbe pas les applications existantes. Par exemple, les appels d’API doivent utiliser une table de vecteurs:
org $04c4;
;;
; open a file for appending if it exists
; @param IX - pointer to ASCIIZ file path
; @throws sets carry flag on error
;;
SEFileAppend:
jp v_open_w_append; // $00
Lorsque vous comparez des caractères ASCII, utilisez le caractère et non le point de code. Par exemple:
cp '('; // opening parenthesis?
En Z80, le point-virgule ( ; ) indique qu’un commentaire suit. Cependant, il est le plus souvent utilisé comme terminaison de ligne. Les environnements de développement intégrés modernes sont conçus pour cela. Par conséquent, chaque ligne doit se terminer par un point-virgule. Les commentaires doivent être précédés d’une double barre oblique ( // ) pour plus de visibilité. Les commentaires autonomes doivent être écrits comme suit:
; // this is a standalone comment
Les commentaires en ligne doivent commencer au dixième taquet de tabulation (colonne 40), par exemple:
di; // interrupts off
Les commentaires doivent être aussi courts que possible pour indiquer ce que fait le code. Lorsqu’une instruction ne peut avoir qu’une seule signification, il n’est pas nécessaire de commenter le code.
Utilisez des majuscules pour les noms de registres dans les commentaires. Par exemple:
ld d, e; // E to D
Dans la mesure du possible, les données doivent être stockées séparément du code.
Utiliser un fichier de définitions pour déclarer:
Si vous utilisez une large gamme de registres d’index, par exemple comme un ensemble de variables, définissez le décalage avec le nom de la variable et un trait de soulignement. Par exemple: _kstate.
Les lignes ne doivent pas comporter plus de 80 caractères pour être affichées sur un terminal standard. Les commentaires en ligne doivent se situer au point 40 caractères afin d’apparaître sur la ligne suivante sur un écran de 40 colonnes.
Utilisez les macros avec parcimonie. Les différents assembleurs utilisent des syntaxes différentes et leur conversion peut prendre beaucoup de temps. Elles fonctionnent mieux pour les codes pseudo op.
Définir des noms significatifs pour les constantes et les variables. Éviter les nombres magiques.
Utilisez la décimale dans la mesure du possible.
Utilisez toujours le langage binaire pour les opérations par bit (AND, OR, XOR). Par exemple, et %00001111.
Écrivez l’hexadécimal avec des lettres minuscules et le signe du dollar en tête. Par exemple, $801c.
N’utilisez jamais de pseudo-codes op. La prise en charge n’est pas uniforme d’un assembleur à l’autre. Si vous devez le faire, définissez un code pseudo-op comme une macro.
Utilisez le script Perl asmdoc pour générer des documents d’API pour les routines publiques.
;;
; Short description.
; @author Name of contributing author.
; @deprecated Version deprecated in and replacement module.
; @param HL - Register contents.
; @return Result in register, such as <code>HL</code>.
; @see <a href="www.example.com">External reference</a>.
; @since Version in which module was introduced.
; @throws Error number and description handled by RST 8 routine.
; @version Version in which the module was last udpated.
;;
Une routine est quelque peu analogue à une fonction en C. Une routine publique est précédée d’une définition asmdoc. Les noms des routines et des sous-programmes sont terminés par deux points. Les instructions de la routine ou du sous-programme sont indentées d’une tabulation. Par exemple, les instructions de la routine ou du sous-programme sont indentées d’une tabulation:
joystick:
in a, (stick); // read joystick
ld (jstate), a; // store in system variable
ret; // end of subroutine
Le code auto-modifiant doit être évité à deux exceptions près:
Divisez le code source en ensembles de modules apparentés et incluez ces modules dans le fichier d’assemblage principal. Les modules doivent commencer par un commentaire spécial. Par exemple:
;;
; // --- ARITHMETIC ROUTINES -------------------------------------------------
;;
:
Utiliser les minuscules dans la mesure du possible. Utiliser la camelCase de préférence aux caractères de soulignement ( _ ). Réserver les MAJUSCULES aux substitutions dans les commentaires. Par exemple:
xor a; // LD A, 0
Utilise des tabulations (une tabulation correspond à quatre caractères). Cela permet d’accélérer les temps de recherche et de compilation.
Image: Détail de Rodnay Zaks’ “Programming the Z80” (Sybex)