Exemples d'en-tête de commentaire SQL
Je voudrais juste voir aussi à quoi ressemblent les en-têtes de commentaires des procédures stockées, des fonctions, etc. des peuples (donc, postez vos exemples) ... Je n'ai que vraiment vu ce que SQL Server Management Studio crée, mais je suis intéressé par l'apparence des autres peuples ... le formatage, les caractères utilisés, les informations de procédure/détails, etc., sont ce qui les rend vraiment différents ...
En-tête de commentaire de procédure stockée SQL Server Management Studio (version 9):
-- =============================================
-- Author: Name
-- Create date:
-- Description:
-- =============================================
Puis-je préciser 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 intégrés au code par le programmeur. C’est un crime 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 <br>
set linesize 180<br>
spool template.log
/*<br>
##########################################################################<br>
-- Name : Template.sql<br>
-- Date : (sysdate) <br>
-- Author : Duncan van der Zalm - dvdzalm<br>
-- Company : stanDaarD-Z.nl<br>
-- Purpose : <br>
-- Usage sqlplus <br>
-- Impact :<br>
-- Required grants : sel on A, upd on B, drop on C<br>
-- Called by : some other process<br
##########################################################################<br>
-- ver user date change <br>
-- 1.0 DDZ 20110622 initial<br>
##########################################################################<br>
*/<br>
sho user<br>
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
Je sais que ce post 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 et les commentaires verbeux, 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 expliquer l'intérêt d'écrire du code bien formaté et fortement commenté. Beaucoup ont été écrits pour être aussi concis que possible, et il peut parfois falloir des jours pour comprendre le sens 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 les commenter correctement.
Expliquez-le comme si vous dirigiez un développeur junior. Supposons que la personne qui le lit sache très peu de choses sur le domaine fonctionnel qu’elle adresse et n’a qu’une compréhension limitée de SQL. Pourquoi? Souvent, les gens doivent examiner les procédures pour les comprendre, même s'ils n'ont aucune 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. Ajoutez des blocs de commentaires aux principales sections fonctionnelles telles que:
/***********************************
** Process all new Inventory records
** Verify quantities and mark as
** available to ship.
************************************/
Ajoutez de nombreux commentaires en ligne expliquant tous les critères, sauf les plus élémentaires, et TOUJOURS formater votre code pour en améliorer la lisibilité. Les longues pages verticales de code indenté sont préférables aux larges et courtes. Il est ainsi plus facile de voir où les blocs de code commencent et se terminent des années plus tard, lorsque quelqu'un d'autre prend en charge votre code. Parfois, le code large et non mis en retrait est plus lisible. Si c'est le cas, utilisez-le, mais uniquement 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
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
------------------------------------------------------------
En passant, tous les commentaires que je place dans le code SQL utilisent toujours le format suivant:
/ * Commentaire * /
Comme par le passé, j’ai eu des problèmes de scripting (avec SQL Server) qui enchaîne les lignes et commence à commenter les commentaires.
Voir si cela convient à votre besoin:
/*
Notes on parameters: Give the details of all parameters supplied to the proc
This procedure will perform the following tasks: Give details description of the intent of the proc
Additional notes: Give information of something that you think needs additional mention, though is not directly related to the proc
Modification History: 07/11/2001 ACL TICKET/BUGID CHANGE DESCRIPTION
*/
Voici ce que j'utilise actuellement. Le triple commentaire (/ */*/*) est destiné à une intégration qui extrait les commentaires d'en-tête de la définition de l'objet.
/*/*/*
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.
*/*/*/
Voici ma variante préférée:
/* =====================================================================
DESC: Some notes about what this does
tabbed in if you need additional lines
NOTES: Additional notes
tabbed in if you need additional lines
======================================================================== */
-- Author:
--
-- Original creation date:
--
-- Description: