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 

Exemple :

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

Exemple :

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 * * * * *