Exemples d’en-tête de commentaire SQL

J’aimerais aussi voir à quoi ressemblent les en-têtes de commentaires Procédure / Fonction stockée, etc. le formatage, les caractères utilisés, les informations / détails de la procédure, etc. Je suppose que c’est ce qui les rend vraiment différents …

SQL Server Management Studio (version 9) stocké en-tête de commentaire de procédure stockée:

-- ============================================= -- Author: Name -- Create date: -- Description: -- ============================================= 

Puis-je indiquer que tous ces champs “Historique des modifications” et “Date de modification” peuvent et doivent être obtenus à partir de votre logiciel de contrôle de version, plutôt que d’être incorporés dans le code par le programmeur. C’est un peu moins que les programmeurs C (par exemple) ont appris il ya longtemps.

 /****************************** ** File: ** Name: ** Desc: ** Auth: ** Date: ************************** ** Change History ************************** ** PR Date Author Description ** -- -------- ------- ------------------------------------ ** 1 01/10/2008 Dan added inner join *******************************/ 
 -- -- STORED PROCEDURE -- Name of stored procedure. -- -- DESCRIPTION -- Business description of the stored procedure's functionality. -- -- PARAMETERS -- @InputParameter1 -- * Description of @InputParameter1 and how it is used. -- -- RETURN VALUE -- 0 - No Error. -- -1000 - Description of cause of non-zero return value. -- -- PROGRAMMING NOTES -- Gotchas and other notes for your fellow programmer. -- -- CHANGE HISTORY -- 05 May 2009 - Who -- * More comprehensive description of the change than that included with the -- source code commit message. -- 

Nous utilisons quelque chose comme ça et très utile pour moi.

 /* Description: Author: Create Date: Param: Return: Modified Date: Modification: */ 
 ------------------------------------------------------------------------------- -- Author name -- Created date -- Purpose description of the business/technical purpose -- using multiple lines as needed -- Copyright © yyyy, Company Name, All Rights Reserved ------------------------------------------------------------------------------- -- Modification History -- -- 01/01/0000 developer full name -- A comprehensive description of the changes. The description may use as -- many lines as needed. ------------------------------------------------------------------------------- 
 -- [why did we write this?] -- [auto-generated change control info] 
 set timing on 
set linesize 180
spool template.log /*
##########################################################################
-- Name : Template.sql
-- Date : (sysdate)
-- Author : Duncan van der Zalm - dvdzalm
-- Company : stanDaarD-Z.nl
-- Purpose :
-- Usage sqlplus
-- Impact :
-- Required grants : sel on A, upd on B, drop on C
-- Called by : some other process
-- ver user date change
-- 1.0 DDZ 20110622 initial
##########################################################################
*/
sho user
select name from v$database; select to_char(sysdate, 'Day DD Month yyyy HH24:MI:SS') "Start time" from dual ; -- script select to_char(sysdate, 'Day DD Month yyyy HH24:MI:SS') "End time" from dual ; spool off

L’en-tête que nous utilisons actuellement ressemble à ceci:

 --------------------------------------------------- -- Produced By : Our company -- URL : www.company.com -- Author : me -- Date : yesterday -- Purpose : to do something -- Called by : some other process -- Modifications : some other guy - today - to fix my bug ------------------------------------------------------------ 

Sur une note de côté, tous les commentaires que je place dans le SQL j’utilise toujours le format:

/ * Commentaire * /

Comme par le passé, j’avais des problèmes de scripting (par SQL Server) qui compliquaient les lignes et les commentaires – ont mis en commentaire le code SQL requirejs …. mais cela pourrait être moi.

Voir si cela correspond à votre exigence:

/*

  • Notes sur les parameters: donnez les détails de tous les parameters fournis au proc

  • Cette procédure effectuera les tâches suivantes: Donner des détails sur le but de la procédure

  • Notes complémentaires: Donner des informations sur quelque chose qui, selon vous, nécessite une mention supplémentaire, mais n’est pas directement lié à la proc

  • Historique des modifications: 07/11/2001 DESCRIPTION DES BILLETS / CHANGEMENTS D’ACL

* /

 -- Author: -- -- Original creation date: -- -- Description: 

Voici ce que j’utilise actuellement. Le sortingple commentaire (/ * / * / *) concerne une intégration qui extrait les commentaires d’en-tête de la définition de l’object.

 /*/*/* Name: pr_ProcName Author: Joe Smith Written: 6/15/16 Purpose: Short description about the proc. Edit History: 6/15/16 - Joe Smith + Initial creation. 6/22/16 - Jaden Smith + Change source to blahblah + Optimized JOIN 6/30/16 - Joe Smith + Reverted changes made by Jaden. */*/*/ 

Je sais que cet article est ancien, mais le code bien formaté ne se démode jamais.

J’utilise ce modèle pour toutes mes procédures. Certaines personnes n’aiment pas le code explicite et les commentaires, mais en tant que personne qui doit fréquemment mettre à jour des procédures stockées qui n’ont pas été touchées depuis le milieu des années 90, je peux vous dire qu’il est utile d’écrire du code bien formaté et fortement commenté. Beaucoup ont été écrites pour être aussi concises que possible, et il faut parfois des jours pour comprendre l’intention d’une procédure. Il est assez facile de voir ce que fait un bloc de code en le lisant simplement, mais il est beaucoup plus difficile (et parfois impossible) de comprendre l’intention du code sans commenter correctement.

Expliquez-le comme si vous passiez par un développeur junior. Supposons que la personne qui la lit sache peu de choses sur le domaine fonctionnel auquel elle s’adresse et que sa compréhension du langage SQL est limitée. Pourquoi? Souvent, les gens doivent examiner les procédures pour les comprendre, même s’ils n’ont pas l’intention de les modifier.

 /*************************************************************************************************** Procedure: dbo.usp_DoSomeStuff Create Date: 2018-01-25 Author: Joe Expert Description: Verbose description of what the query does goes here. Be specific and don't be afraid to say too much. More is better, than less, every single time. Think about "what, when, where, how and why" when authoring a description. Call by: [schema.usp_ProcThatCallsThis] [Application Name] [Job] [PLC/Interface] Affected table(s): [schema.TableModifiedByProc1] [schema.TableModifiedByProc2] Used By: Functional Area this is use in, for example, Payroll, Accounting, Finance Parameter(s): @param1 - description and usage @param2 - description and usage Usage: EXEC dbo.usp_DoSomeStuff @param1 = 1, @param2 = 3, @param3 = 2 Additional notes or caveats about this object, like where is can and cannot be run, or gotchas to watch for when using it. **************************************************************************************************** SUMMARY OF CHANGES Date(yyyy-mm-dd) Author Comments ------------------- ------------------- ------------------------------------------------------------ 2012-04-27 John Usdaworkhur Move Z <-> X was done in a single step. Warehouse does not allow this. Converted to two step process. Z <-> 7 <-> X 1) move class Z to class 7 2) move class 7 to class X 2018-03-22 Maan Widaplan General formatting and added header information. 2018-03-22 Maan Widaplan Added logic to automatically Move G <-> H after 12 months. ***************************************************************************************************/ 

En plus de cet en-tête, votre code doit être bien commenté et décrit de haut en bas. Ajouter des blocs de commentaires aux principales sections fonctionnelles comme:

 /*********************************** ** Process all new Inventory records ** Verify quantities and mark as ** available to ship. ************************************/ 

Ajoutez beaucoup de commentaires en ligne expliquant tous les critères sauf le plus simple, et formatez TOUJOURS votre code pour plus de lisibilité. Les longues pages verticales de code en retrait sont meilleures que les courtes et permettent de voir plus facilement où les blocs de code commencent et finissent des années plus tard lorsque quelqu’un prend en charge votre code. Parfois, le code large et non indenté est plus lisible. Si oui, utilisez-le, mais seulement lorsque cela est nécessaire.

 UPDATE Pallets SET class_code = 'X' WHERE AND class_code != 'D' AND class_code = 'Z' AND historical = 'N' AND quantity > 0 AND GETDATE() > DATEADD(minute, 30, creation_date) AND pallet_id IN ( -- Only update pallets that we've created an Adjustment record for SELECT Adjust_ID FROM Adjustments WHERE AdjustmentStatus = 0 AND RecID > @MaxAdjNumber