Примеры заголовков SQL-комментариев

Ответ 1

Могу ли я указать, что все эти поля "изменить историю" и "измененная дата" могут и должны быть получены из вашего программного обеспечения для управления версиями, а не встраиваться в код программистом. Это урок, который C (например) программисты узнали давно.

Ответ 2

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

Ответ 3

--
-- STORED PROCEDURE
--     Name of stored procedure.
--
-- DESCRIPTION
--     Business description of the stored procedure 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.
--

Ответ 4

Мы используем что-то подобное и очень полезно для меня.

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

Ответ 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.
-------------------------------------------------------------------------------

Ответ 6

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

Ответ 7

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

Ответ 8

Я знаю, что этот пост - древний, но хорошо отформатированный код никогда не выходит из моды.

Я использую этот шаблон для всех моих процедур. Некоторым людям не нравится подробный код и комментарии, но как человек, которому часто приходится обновлять хранимые процедуры, которые не затрагивались с середины 90-х годов, я могу сказать вам ценность написания хорошо отформатированного и тщательно прокомментированного кода. Многие были написаны, чтобы быть как можно более краткими, и иногда может потребоваться несколько дней, чтобы понять смысл процедуры. Довольно просто увидеть, что делает блок кода, просто прочитав его, но гораздо сложнее (а иногда и невозможно) понять смысл кода без правильного комментирования.

Объясните это так, будто вы проходите через младшего разработчика. Предположим, что человек, читающий его, почти ничего не знает о функциональной области, к которой он обращается, и имеет ограниченное понимание SQL. Зачем? Много раз люди должны смотреть на процедуры, чтобы понять их, даже если они не намерены или бизнес изменяет их.

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

В дополнение к этому заголовку, ваш код должен быть хорошо прокомментирован и обрисован сверху вниз. Добавьте блоки комментариев к основным функциональным разделам, таким как:

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

Добавьте множество встроенных комментариев, объясняющих все критерии, кроме самых основных, и ВСЕГДА форматируйте ваш код для удобства чтения. Длинные вертикальные страницы кода с отступом лучше, чем широкие короткие и позволяют намного легче увидеть, где блоки кода начинаются и заканчиваются спустя годы, когда кто-то другой поддерживает ваш код. Иногда широкий, без отступа код более читабелен. Если так, используйте это, но только когда необходимо.

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

Ответ 9

Используемый нами заголовок выглядит так:

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

С другой стороны, любые комментарии, которые я помещаю в SQL, всегда используют формат:

/* Комментарий */

Как и в прошлом, у меня были проблемы, при которых скриптинг (с помощью SQL Server) делает забавные вещи, обертывающие строки вокруг и начинающие комментарии - комментируют требуемый SQL... но это может быть только я.

Ответ 10

Посмотрите, соответствует ли это вашему требованию:

/*  

* 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


*/

Ответ 11

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

Ответ 12

Вот что я сейчас использую. Тройной комментарий (/*/*/*) предназначен для интеграции, который выбирает комментарии заголовка из определения объекта.

/*/*/*

    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.

*/*/*/

Ответ 13

Вот мой предпочтительный вариант:

/* =====================================================================
DESC:   Some notes about what this does
           tabbed in if you need additional lines
NOTES:  Additional notes
           tabbed in if you need additional lines
======================================================================== */