Exemples d'en-tête de commentaire SQL

Question

J'aimerais juste voir à quoi ressemblent les en-têtes de commentaires des procédures stockées/fonctions etc... (alors postez vos exemples)... Je n'ai vraiment vu que ce que le SQL Server Management Studio crée mais je suis intéressé par ce à quoi ressemblent les autres... 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...

En-tête de commentaire par défaut de la procédure stockée de SQL Server Management Studio (version 9) :

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

Answer 1

/******************************
** File:    
** Name:
** Desc:
** Auth:
** Date:
**************************
** Change History
**************************
** PR   Date        Author  Description 
** --   --------   -------   ------------------------------------
** 1    01/10/2008      Dan      added  inner join
*******************************/

Answer 2

Puis-je souligner 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 dans le code par le programmeur. C'est une leçon que les programmeurs C (par exemple) ont apprise il y a longtemps.

Answer 3

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

Answer 4

Je sais que ce billet est ancien, mais un 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 verbeux 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 la valeur de l'écriture d'un code bien formaté et fortement commenté. Beaucoup ont été écrits pour être aussi concis que possible, et il faut parfois des jours pour saisir 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 un commentaire approprié.

Expliquez-le comme si vous le faisiez pour un jeune développeur. Partez du principe que la personne qui le lit connaît peu ou pas du tout le domaine fonctionnel auquel il s'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 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 souligné de haut en bas. Ajoutez des blocs de commentaires aux principales sections fonctionnelles comme :

/***********************************
**  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 mettez TOUJOURS votre code en forme pour qu'il soit lisible. De longues pages verticales de code indenté sont préférables à de larges pages courtes et permettent de voir beaucoup plus facilement où commencent et se terminent les blocs de code, des années plus tard, lorsque quelqu'un d'autre soutient votre code. Parfois, un code large, sans indentation, est plus lisible. Si c'est le cas, utilisez-le, mais seulement si 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

Modifier

J'ai récemment abandonné les blocs de commentaires de type bannière car il est facile de séparer les commentaires du haut et du bas lors de la mise à jour du code au fil du temps. On peut se retrouver avec du code logiquement séparé dans des blocs de commentaires qui disent être ensemble, ce qui crée plus de problèmes que cela n'en résout. J'ai commencé à entourer les sections de déclarations multiples qui vont ensemble avec des blocs BEGIN .... END, et à placer mes commentaires de flux à côté de la première ligne de chaque déclaration. Cela a l'avantage de vous permettre de réduire le bloc de code et de lire clairement les commentaires de haut niveau, et lorsque vous ouvrez une section, vous pouvez faire de même avec les déclarations individuelles. Cela se prête également très bien aux niveaux de code fortement imbriqués. Elle est précieuse lorsque votre procédure commence à atteindre les 200-400 lignes et n'ajoute aucune ligne à une procédure déjà longue.

Élargi

Effondré

Answer 5

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