SQL 注释头示例
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/1085672/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
SQL comment header examples
提问by davidsleeps
Would just like too see what peoples Stored Procedure/Function etc comment headers look like (so post your examples)...I've only really seen what the SQL Server Management Studio creates but am interested in what other peoples look like...the formatting, characters used, procedure information/details etc I guess are what really makes them different...
也想看看人们的存储过程/函数等评论标题是什么样的（所以发布你的例子）......我只真正看到了 SQL Server Management Studio 创建的内容，但对其他人的外观感兴趣......格式、使用的字符、程序信息/细节等我想是真正让它们与众不同的原因......
SQL Server Management Studio (version 9) stored procedure comment header default:
SQL Server Management Studio（版本 9）存储过程注释标头默认：
-- =============================================
-- Author: Name
-- Create date:
-- Description:
-- =============================================
回答by Hagai L
/******************************
** File:
** Name:
** Desc:
** Auth:
** Date:
**************************
** Change History
**************************
** PR Date Author Description
** -- -------- ------- ------------------------------------
** 1 01/10/2008 Dan added inner join
*******************************/
回答by Convict
--
-- 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.
--
回答by Nick Fotopoulos
I know this post is ancient, but well formatted code never goes out of style.
我知道这篇文章很古老，但格式良好的代码永远不会过时。
I use this template for all of my procedures. Some people don't like verbose code and comments, but as someone who frequently has to update stored procedures that haven't been touched since the mid 90s, I can tell you the value of writing well formatted and heavily commented code. Many were written to be as concise as possible, and it can sometimes take days to grasp the intent of a procedure. It's quite easy to see what a block of code is doing by simply reading it, but its far harder (and sometimes impossible) is understanding the intent of the code without proper commenting.
我在所有程序中都使用此模板。有些人不喜欢冗长的代码和注释，但作为经常需要更新自 90 年代中期以来就没有接触过的存储过程的人，我可以告诉您编写格式良好且注释较多的代码的价值。许多都写得尽可能简洁，有时可能需要几天时间才能掌握程序的意图。通过简单地阅读代码块很容易看出它在做什么，但更难（有时甚至不可能）理解代码的意图而没有适当的注释。
Explain it like you are walking a junior developer through it. Assume the person reading it knows little to nothing about functional area it's addressing and only has a limited understanding of SQL. Why? Many times people have to look at procedures to understand them even when they have no intention of or business modifying them.
像您在带领初级开发人员完成它一样解释它。假设阅读它的人对它所寻址的功能区知之甚少，而且对 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.
***************************************************************************************************/
In addition to this header, your code should be well commented and outlined from top to bottom. Add comment blocks to major functional sections like:
除了这个标题之外，你的代码应该从上到下很好地注释和概述。将注释块添加到主要功能部分，例如：
/***********************************
** Process all new Inventory records
** Verify quantities and mark as
** available to ship.
************************************/
Add lots of inline comments explaining all criteria except the most basic, and ALWAYS format your code for readability. Long vertical pages of indented code are better than wide short ones and make it far easier to see where code blocks begin and end years later when someone else is supporting your code. Sometimes wide, non-indented code is more readable. If so, use that, but only when necessary.
添加大量内嵌注释，解释除最基本的标准之外的所有标准，并始终格式化您的代码以提高可读性。缩进代码的长垂直页面比宽短页面更好，并且在其他人支持您的代码时更容易查看代码块的开始和结束位置。有时宽的、非缩进的代码更具可读性。如果是这样，请使用它，但仅在必要时使用。
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
回答by KuldipMCA
We use something like this and very useful for me .
我们使用这样的东西，对我来说非常有用。
/*
Description:
Author:
Create Date:
Param:
Return:
Modified Date:
Modification:
*/
回答by Jay
-------------------------------------------------------------------------------
-- 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.
-------------------------------------------------------------------------------
回答by Jeffrey Kemp
-- [why did we write this?]
-- [auto-generated change control info]
回答by Duncan
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
回答by Iain Hoult
The header that we currently use looks like this:
我们当前使用的标头如下所示：
---------------------------------------------------
-- 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
------------------------------------------------------------
On a side note, any comments that I place within the SQL i always use the format:
附带说明一下，我在 SQL 中放置的任何注释总是使用以下格式：
/* Comment */
/* 评论 */
As in the past I had problems where scripting (by SQL Server) does funny things wrapping lines round and comments starting -- have commented out required SQL.... but that might just be me.
和过去一样，我在脚本编写（由 SQL Server 中）做一些有趣的事情时遇到了问题，包括换行和开始注释——已经注释掉了所需的 SQL ......但这可能只是我。
回答by Atul
See if this suits your requirement:
看看这是否符合您的要求：
/*
* 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
*/
回答by chazbot7
Here's what I currently use. The triple comment ( / * / * / * ) is for an integration that picks out header comments from the object definition.
这是我目前使用的。三重注释 ( /* /* /* ) 用于从对象定义中挑选标题注释的集成。
/*/*/*
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.
*/*/*/
