SQL 注释头示例 - 开卷题库

小开

我们用这样的东西，对我很有用。

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

小开

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

小开

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

小开

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

小开

看看这是否符合你的要求:

/*


* 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




*/

小开

我们当前使用的头部如下所示:

---------------------------------------------------
-- 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 i 中放置的任何注释都使用以下格式:

/* 评论 */

和过去一样，我也遇到过这样的问题: 脚本(由 SQLServer 编写)做了一些有趣的事情，包围了行和注释开始——注释掉了所需的 SQL..。但那可能只是我。

小开

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

小开

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

小开

这是我目前使用的。三重注释(/*/*/*)用于从对象定义中挑选头注释的集成。

/*/*/*


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.


*/*/*/

小开

我知道这篇文章很古老，但是格式良好的代码永远不会过时。

我的所有过程都使用这个模板。有些人不喜欢冗长的代码和注释，但是作为一个经常需要更新自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

剪辑

我最近放弃了横幅样式注释块，因为随着代码随着时间的推移不断更新，顶部和底部的注释很容易分开。最终，注释块中逻辑上独立的代码可能会说它们属于一起，从而造成的问题多于解决的问题。相反，我已经开始围绕属于 BEGIN... END 块的多个语句部分，并将我的 flow 注释放在每个语句的第一行旁边。这样做的好处是可以折叠代码块，并且能够清楚地读取高级流注释，当打开一个部分的分支时，就可以对其中的各个语句执行相同的操作。这也非常适合于高度嵌套的代码级别。当你的过程开始慢慢进入200-400行的范围，并且不会给已经很长的过程增加任何行量时，这是非常宝贵的。

变大了

崩溃了

小开

下面是我喜欢的变体:

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