Standards de codage API : du nommage à la bibliothèque

1.Pourquoi les conventions de nommage seules ne font pas un standard

Presque toute équipe qui décide de « standardiser » commence par les préfixes. bMotorRun, iCounter, rPressure — convenus en une après-midi, consignés sur une page, puis silencieusement érodés au fil des deux projets suivants.

La cause de cette érosion n'est pas la négligence. C'est qu'un tableau de préfixes répond à la plus petite question qu'un standard doit traiter. Il dit comment nommer une variable. Il ne dit rien de ce qu'un bloc fonctionnel doit exposer à son interface, de qui a le droit de modifier un bloc de bibliothèque, ni de ce qui se passe lorsqu'un projet a besoin d'une variante de quelque chose qui existe déjà.

Ce sont pourtant ces questions qui déterminent si un deuxième ingénieur peut reprendre le projet — et ce sont précisément celles que l'on saute, parce qu'elles exigent des décisions et non des conventions.

2.Les quatre niveaux d'un standard viable

2.1.Niveau 1 : un nommage qui tient

Les préfixes de types de données sont le niveau d'entrée et valent leur prix. Le tableau détaillé figure dans l'article sur les bonnes pratiques de programmation API ; pour un standard, ce qui compte vient après le préfixe.

Trois règles portent l'essentiel :

Nommer par fonction, pas par matériel. bConvoyeur3Marche survit à un changement de fournisseur de moteur. bSEW12345Marche non. La variable survit au composant.

Refléter le système de repérage de l'installation. Si le schéma P&ID l'appelle M-301, le logiciel doit porter M301 dans le nom — et non un second univers de nommage parallèle que seul le programmeur comprend. Cette seule règle fait gagner plus de temps à la mise en service que n'importe quelle autre.

Coder l'appartenance, pas l'emplacement. Un nom doit dire à quoi une chose appartient (Convoyeur3_MoteurMarche), pas où elle se trouve par hasard (DB12_Bit3). Les structures se déplacent, le sens non.

2.2.Niveau 2 : le contrat d'interface

C'est ici qu'un standard gagne sa place. Pour chaque bloc fonctionnel réutilisable, on décide une fois et on consigne :

• Qu'est-ce qui est obligatoire à l'interface ? La plupart des standards maison exigent au minimum une validation, une sortie de défaut et un mot d'état. Si chaque bloc a la même forme, la logique de niveau supérieur peut les traiter uniformément.
• À qui appartiennent les données d'instance ? Les DB d'instance appartiennent au niveau appelant, pas à l'auteur du bloc.
• À quoi le bloc a-t-il le droit d'accéder ? Un bloc réutilisable qui écrit des mémentos globaux n'est pas réutilisable — c'est une mine. La règle « un bloc de bibliothèque lit et écrit exclusivement via son interface » est, dans la plupart des standards, la ligne la plus précieuse.
• Comment les défauts sont-ils signalés ? Choisir un mécanisme et l'appliquer partout. Beaucoup d'équipes utilisent un mot d'état conforme à NAMUR NE 107, afin que le diagnostic soit identique sur toute l'installation.

(*
  Contrat d'interface pour tout bloc de bibliothèque de ce standard :
    IN   : bValidation      — aucune action tant que FALSE
    IN   : stConfig         — tous les paramètres, aucun nombre magique interne
    OUT  : bPret, bDefaut
    OUT  : wStatusNAMUR     — diagnostic uniforme sur toute l'installation
  Le bloc ne lit ni n'écrit rien en dehors de cette interface.
*)

Voici à quoi cela ressemble dans un projet réel — les numéros de groupe classent les blocs par partie d'installation, et le bloc d'entraînement porte exactement l'interface définie comme contrat ci-dessus :

2.3.Niveau 3 : une bibliothèque, pas un dossier de copies

Ce qui sépare un standard d'une habitude, c'est de savoir si les blocs résident quelque part avec une version.

• Une source unique. Un bloc de bibliothèque existe une seule fois. Les projets le référencent, ils ne le copient pas.
• Versionnement avec discipline de release. Une version de bibliothèque se publie, elle ne se modifie pas. Si un projet a besoin d'un changement, il reçoit soit une nouvelle version, soit un bloc spécifique au projet, explicitement identifié comme tel.
• Un journal des modifications par bloc. Pas par projet — par bloc, car c'est l'unité réutilisée.
• Une voie d'exception définie. Tout standard finit par être enfreint. Un standard sans voie de dérogation définie sera contourné en silence, et c'est le pire résultat. Consignez qui approuve une exception et où elle est enregistrée.

2.4.Niveau 4 : une application qui ne freine personne

Un standard que personne ne contrôle est un document, pas un standard. Trois niveaux, par effort croissant :

Outillage. TIA Portal V18 et versions ultérieures intègre un Code Quality Check qui signale automatiquement les écarts aux conventions de nommage. Il ne vérifie pas votre contrat d'interface, mais il retire gratuitement la partie la plus fastidieuse d'une revue.

Checklist de revue. Cinq à sept questions oui/non, pas un traité. Chaque bloc de bibliothèque passe-t-il uniquement par son interface ? Chaque constante non explicite a-t-elle une source ? Le mécanisme de défaut est-il celui du standard ? Une checklist de dix minutes est utilisée ; une d'une heure ne l'est pas.

Contrôles structurels automatisés. Avec TIA Openness, un projet s'exporte en format texte et se vérifie par programme — nommage des blocs, forme des interfaces, accès globaux interdits. Cela vaut la peine une fois la bibliothèque stabilisée, pas avant.

3.Ce qu'un standard ne doit délibérément pas faire

La sur-standardisation est un mode de défaillance réel, plus difficile à défaire que l'absence de standard.

• Ne pas imposer le langage par type de bloc. Le choix se fait par tâche — le standard doit encadrer sa justification, pas le dicter. Quel langage convient à quoi : voir les cinq langages de la CEI 61131-3.
• Ne pas prescrire l'implémentation interne. Le contrat, c'est l'interface. La façon dont un bloc résout sa tâche relève de son auteur.
• Ne pas figer le standard. Un standard inchangé depuis trois ans n'est pas stable : il est inutilisé.

4.Mise au point : « Top 20 Secure PLC Coding Practices »

Qui cherche des standards de codage API tombe dessus. Il vaut la peine de savoir ce que c'est — et ce que ce n'est pas.

C'est une initiative communautaire consacrée spécifiquement au durcissement sécuritaire de la logique de commande : validation des entrées, contrôles de plausibilité, surveillance des valeurs inattendues, restriction de ce que l'automate accepte de l'extérieur. Techniquement précieux, et de plus en plus pertinent avec l'orientation réglementaire européenne sur les machines et la cyber-résilience.

Mais c'est un autre axe que celui de cet article. Il répond à « comment rendre ma logique plus difficile à détourner », pas à « comment rendre mon projet maintenable par le prochain ingénieur ». Une équipe a besoin des deux, et aucun ne remplace l'autre. Traiter la liste sécurité comme un standard de codage général laisse les questions de maintenabilité sans réponse.

5.Introduire un standard dans une installation existante

La raison la plus fréquente pour laquelle les standards ne voient jamais le jour : l'existant est trop volumineux à convertir, donc personne ne commence.

Ce qui fonctionne, c'est de ne rien convertir :

1. N'appliquer le standard qu'aux nouveaux blocs. À partir d'aujourd'hui, tout ce qui est neuf le suit. Rien d'ancien n'est touché.
2. Mettre à niveau au contact. Si un bloc doit de toute façon être modifié, il est porté au standard dans la foulée. Sur deux ou trois projets, cela couvre exactement les blocs qui comptent — ceux que l'on touche.
3. Ne jamais convertir pour convertir. Réécrire un bloc qui tourne sans modification depuis huit ans crée du risque et n'apporte rien. Les blocs que personne ne touche, personne n'a besoin de les lire.
4. Documenter la frontière. Une ligne par bloc indiquant s'il suit le standard actuel épargne les devinettes au prochain ingénieur.

Cela ne coûte rien en amont et produit des intérêts composés. Un projet de conversion intégrale, à l'inverse, cale généralement à mi-chemin et laisse un existant avec deux standards au lieu d'un — mesurablement pire que le point de départ.

6.Conclusion

• Un tableau de préfixes n'est pas un standard. C'est au contrat d'interface que se joue la maintenabilité.
• Nommer par fonction et refléter le repérage de l'installation — la variable survit au composant.
• Une bibliothèque avec versions et journal transforme une habitude en standard.
• Définir la voie d'exception, sinon la dérogation devient silencieuse.
• N'appliquer qu'aux blocs neufs et à ceux que l'on touche. Les conversions intégrales calent ; l'adoption progressive se capitalise.

7.Pour aller plus loin

• Programmation API : 8 bonnes pratiques pour un code propre – les fondations, tableau de préfixes complet inclus
• Documentation API : ce qu'elle doit contenir et ce qui compte à la remise – comment un standard se manifeste à la remise
• Les 5 langages de programmation API selon la CEI 61131-3 – choisir par tâche au lieu d'évacuer le choix par standardisation