lineas - comment on column sql server

Ejemplos de encabezado de comentario SQL

Question

También me gustaría ver qué aspecto tienen los encabezados de comentario de Stored Procedure / Function, etc. (así que publique sus ejemplos) ... Realmente solo he visto lo que crea SQL Server Management Studio, pero estoy interesado en cómo se ven las demás personas ... el formato, los caracteres utilizados, la información del procedimiento / detalles, etc. Supongo que son lo que realmente los hace diferentes ...

SQL Server Management Studio (versión 9) almacenó el procedimiento predeterminado de encabezado de comentario de procedimiento:

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

Answer 1

¿Puedo señalar que todos estos campos de "historial de cambios" y "fecha de modificación" pueden y deben obtenerse de su software de control de versiones, en lugar de estar incrustados en el código por el programador? Esta es una idea menor que los programadores C (por ejemplo) aprendieron hace mucho tiempo.

Answer 2

El encabezado que usamos actualmente se ve así:

---------------------------------------------------
-- 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 una nota lateral, cualquier comentario que coloque dentro del SQL siempre uso el formato:

/ * Comentario * /

Al igual que en el pasado, tuve problemas cuando las secuencias de comandos (por SQL Server) hacen cosas divertidas envolviendo líneas y comenzando comentarios - se ha comentado SQL requerido ... pero podría ser solo yo.

Answer 3

Esto es lo que uso actualmente. El comentario triple (/ * / * / *) es para una integración que selecciona comentarios de encabezado de la definición del objeto.

/*/*/*

    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.

*/*/*/

Answer 4

Sé que esta publicación es antigua, pero el código bien formateado nunca pasa de moda.

Uso esta plantilla para todos mis procedimientos. A algunas personas no les gustan los códigos detallados y los comentarios, pero como alguien que frecuentemente tiene que actualizar los procedimientos almacenados que no se han tocado desde mediados de los años 90, puedo decirle el valor de escribir un código bien formateado y muy comentado. Muchos fueron escritos para ser lo más concisos posible, y algunas veces puede llevar días entender el propósito de un procedimiento. Es bastante fácil ver lo que está haciendo un bloque de código simplemente leyéndolo, pero es mucho más difícil (y algunas veces imposible) entender la intención del código sin hacer los comentarios adecuados.

Explícalo como si estuvieras caminando con un desarrollador junior a través de él. Supongamos que la persona que lo lee sabe poco o nada acerca del área funcional a la que se dirige y solo tiene una comprensión limitada de SQL. ¿Por qué? Muchas veces la gente tiene que mirar los procedimientos para comprenderlos, incluso cuando no tienen intención de modificarlos.

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

Además de este encabezado, su código debe ser bien comentado y delineado de arriba a abajo. Agregue bloques de comentarios a las principales secciones funcionales como:

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

Agregue muchos comentarios en línea que explican todos los criterios, excepto el más básico, y formatee SIEMPRE su código para facilitar la lectura. Las páginas verticales largas de código sangrado son mejores que las cortas y hacen que sea más fácil ver dónde comienzan y finalizan los bloques de código cuando alguien más está respaldando su código. A veces, el código amplio sin sangría es más legible. Si es así, úselo, pero solo cuando sea necesario.

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

Answer 5

Usamos algo así y es muy útil para mí.

/*  
Description:   
Author:   
Create Date: 
Param:   
Return:   
Modified Date:  
Modification:   
*/  

Answer 6

Vea si esto satisface su requisito:

/*

• Notas sobre los parámetros: brinde los detalles de todos los parámetros suministrados al proceso

• Este procedimiento realizará las siguientes tareas: Dar detalles de la descripción del intento del proceso

• Notas adicionales: brinde información de algo que cree que necesita una mención adicional, aunque no está directamente relacionado con el proceso

• Historial de modificaciones: 07/11/2001 ACL TICKET / BUGID CHANGE DESCRIPTION

* /

Answer 7

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

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

Answer 9

-- [why did we write this?]
-- [auto-generated change control info]

Answer 10

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

Answer 11

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

Answer 12

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