[ARTICLE] Documentation du code Transact SQL

Bonjour à tous et bonne année !

Voici un des nombreux articles que je viens de publier sur mon site corporate (http://mssqlserver.fr/) et je voudrais vos commentaires :
http://mssqlserver.fr/?p=258
Il s'agit de la façon de documenter le code Transact SQL à l'aide de cartouches, mais aussi pour la correction du code.

Si vous avez des remarques à faire elles sont les bienvennues.

Merci

Bonjour,

Quelques remarques :
- J'aime beaucoup la partie INPUTS qui définit les paramètres. Je commente en général directement dans le code, au niveau des paramètres, et l'avoir séparé dans le cartouche est une bonne idée
- Ne faudrait-il pas aussi définir dans le cartouche l'éventuel domaine de l'input s'il est plus restreint que le type de manière à ne pas avoir besoin de lire le code pour connaître les préconditions ?
- Une bonne partie de ce qui est présent dans ces cartouches n'est-elle pas redondante avec l'utilisation d'un contrôle de source ? Et avec un gestionnaire de bug lié au contrôle de source ? Dans ce cas, on peut alléger le cartouche.

Citation:

---

Envoyé par Monstros Velu

Bonjour,

Quelques remarques :
- J'aime beaucoup la partie INPUTS qui définit les paramètres. Je commente en général directement dans le code, au niveau des paramètres, et l'avoir séparé dans le cartouche est une bonne idée
- Ne faudrait-il pas aussi définir dans le cartouche l'éventuel domaine de l'input s'il est plus restreint que le type de manière à ne pas avoir besoin de lire le code pour connaître les préconditions ?
- Une bonne partie de ce qui est présent dans ces cartouches n'est-elle pas redondante avec l'utilisation d'un contrôle de source ? Et avec un gestionnaire de bug lié au contrôle de source ? Dans ce cas, on peut alléger le cartouche.

---

L'idée est de pouvoir lire et parser le cartouche par un outil adapté.

A +

Comme Monstros Velu, la partie "correction du code" me semble très (trop ?) redondante avec un gestionnaire de source.

L'outils dont tu parles qui doit être capable de parser les cartouches pourrait aussi bien interroger le log d'un git par exemple afin de récupérer les modifications de code et leurs commentaires.

En effet, dans une version 1, 2, 3, tout va bien.
Mais après quelques années de bons et loyaux services, et 4 refontes complètes de l'algo, tu vas avoir 2000 lignes de commentaires (donc 1900 lignes de code commenté) pour au final 15 lignes de code exécuté.

Pour le cartouche, ça me plaît bien.
Personnellement, je serais parti sur une syntaxe existante, comme celle de .NET, à base de XML

Il suffit simplement de remplacer les /// par --- :

Code:

---

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27

--- <summary> --- Substracts two integers and returns the result. --- </summary> --- <returns> --- The difference of two integers. --- </returns> --- <remarks> --- The result is absolute --- </remarks> --- <example> --- <code> --- set @c = dbo.substract(4, 5); --- print @c; -- Displays "1" --- </code> --- </example> --- <param name="a">An integer number.</param> --- <param name="b">An integer number.</param> create or alter function SubStract ( @a integer, @b integer ) returns integer begin return abs(@a - @b); end

---

Le principe dans les grands projets est que quand il y a n modif on passe à une nouvelle release. Ce pourquoi il existe la notion de version.

A +

Citation:

---

Envoyé par SQLpro

L'idée est de pouvoir lire et parser le cartouche par un outil adapté.

A +

---

Chez le client chez qui je travaille actuellement on utilise le versioning de TFS et le cartouche que tu décris (à peu de choses prêt). L'information est redondante parce qu'au départ il n'y avait pas d'outil de versioning mais avec la pratique je me suis aperçu que l'équipe de dev SQL en place (incluant moi) utilisait volontiers l'historique du cartouche dans les procédures avant de passer par TFS (plus rapide ? L'habitude?)

Sur le principe je suis d'accord, c'est redondant et on peut alléger. La plupart des outils de versioning proposent d'ailleurs de récupérer l'historique en cas de migration.

++

C'est surtout pour fournir un template à tous ceux de mes clients qui développent sans outil de versionnement !

A +

2 remarques :
1- Ajouter le relecteur du code
2- gestion du code mort

1- Relecture du code
J'essaie de faire comprendre que l'auteur est le plus mauvais relecteur de son propre code.
Quelque soit sa compétence.
Du coup inscrire le relecteur est un acte responsabilisant. (qui retarde la mise en prod, comme les tests ;) )

2- gestion du code mort
La conservation du code mort pose effectivement le problème de la durée de conservation et du volume.
Je fais comme tout le monde, je développe suivant un cahier des charges précis que je peux consulter dans la gestion de projet afférente... ou presque ;)
Quand le code a été modifié par différentes personnes, pour différentes parties, pour différents objectifs l'imbrication de tout ça fini par rendre la lecture du code mort insupportable.

Petit exemple d'un cycle de modification :
Acte 1 : La procédure utilise plusieurs curseurs et du sql dynamique
Acte 2 : Certains curseurs sont fusionnés en 1
Acte 3 : Ajout de Print
Acte 4 : Abandon des curseurs pour des boucles unitaires (select i=count(*) from ... puis boucle)
Acte 5 : Remplacement des Print par des raiserror (pour suivre l'avancée en temps réel)
Acte 6 : Remplacement de l'ensemble par une instruction merge avec CTE et fonctions analytiques
Avec un peut d'imagination (ou d'expérience) selon le niveau de compétence de chacun des rédacteurs et son style d'écriture on imagine vite l'aspect polymorphe (donc difficilement appréhendable) de la lecture du code.

Ce qui me gène le plus dans la proposition ce sont les balises début et fin de modification.
C'est pas toujours aussi "chirurgical" que dans l'exemple fourni.
Et ça c'est sans compter avec l'ajout/suppression des hints et autres fadaises.