Dans les grands projets informatique, la documentation, hélas souvent oubliée, fait partie des éléments incontournables, destinés à améliorer la productivité. Elle doit être claire, succincte et facile à réaliser. Voici quelques uns des « patrons » (template) que j’utilise.
Pour une procédure stockée :
Le premier cadre de ce cartouche contient les éléments essentiels :
Module : est le nom que je donne au module de code (arbitraire)
Nature : « PROCEDURE » dans une procédure, mais aussi « FUNCTION », « TRIGGER »…
Object : nom complet de l’objet avec sa base et son préfixe de schéma SQL
Create : date de création
Author : les auteurs (un par ligne si plusieurs) avec leurs initiale sous forme de trigramme unique
Version : n° de version
Sytem : Yes/No (spécifique aux procédures), oui si procédure stockée promue à titre système via sp_MS_marksystemobject.
Valid : présente la liste des versions et éventuelles éditions, pour lesquelles l’objet est fonctionnel
Le second cadre contient ma publicité qui fait référence à mes différents sites web ont sont postés certaines de ces routines.
Le troisième cadre (PURPOSE) contient la description du fonctionnement de l’objet.
Le quatrième cadre (INPUTS) contient la liste des paramètres
Il sont décrits avec le motif suivant :
nom_de_la_variable : description de la valeur
S’ils sont aussi en sortie, le mot clef OUTPUT figure en suffixe.
Le cinquième cadre contient un ou plusieurs exemples
Le sixième cadre (facultatif IMPROVE) contient les améliorations introduites au fur et à mesure de l’exploitation
Elles sont décrites avec le motif suivant :
tag (date initiales auteur) : description
- Le tag étant identifié avec trois caractères dièse (#) suivi d’un nombre sur 3 positions.
- La date étant au format ISO : AAAA-MM-JJ
Dans le code de la routine, les lignes modifiées sont repérées à l’aide du tag et des mots clefs begins/ends
Le septième cadre (facultatif BUGFIX) contient les corrections introduites au fur et à mesure de l’exploitation
Le motif est le même que la partie IMPROVE.
Tous les tags, qu’ils soient indifféremment d’amélioration ou de correction, doivent avoir un numéro unique.
Correction du code
Que ce soit pour une amélioration ou une correction, tout le code ancien est conservé en commentaire et le nouveau code est bornés par les tags. En voici un exemple :
Pour une fonction
À peu de choses près c’est le même, seul, le contenu du cadre 1 du cartouche est modifié :
- Le mot clef SYSTEM dans n’a pas à y figurer
- Le mot clef OUTPUT doit y figurer pour préciser le type du paramètre de retour
Au niveau de la nature, précisez : SCALAR_FUNCTION, INLINE_TABLE_FUNCTION, TABLE_FUNCTION, CLR_AGGREGATE_FUNCTION
Pour un déclencheur
À nouveau, à peu de choses près c’est le même :
- Les mots clef SYSTEM et OUTPUT ne doivent pas figurer dans le cadre 1
- Les cadres INPUTS et EXEMPLE ne doivent pas y figurer
Template de cartouches Transact SQL
Frédéric Brouard - SQLpro - ARCHITECTE DE DONNÉES - expert SGBDR et langage SQL
* Le site sur les SGBD relationnels et le SQL : https://sqlpro.developpez.com *
* le blog SQL, SQL Server, SGBDR... sur : https://blog.developpez.com/sqlpro/ *
* Expert Microsoft SQL Server, MVP (Most valuable Professional) depuis 14 ans *
* Entreprise SQL SPOT : modélisation, conseil, audit, optimisation, formation *
* * * * * Enseignant CNAM PACA - ISEN Toulon - CESI Aix en Provence * * * * *