4.3.7 注释脚本

在编写SQL脚本时，编写者当然理解脚本的含义，因为编程需要在一定的环境中完成。我在完成一个项目时，一直在思考这个项目，几乎所有的一切在那一刻都是有意义的。有一次，我为咨询客户开发了一个数据库应用程序，几个人花了几个月的时间编写了查询与程序代码。后来，他们要求我创建一些新的报表。当我阅读这个项目的代码时，发现无法理解其逻辑，我说，"我看不懂这些代码，谁写的？"客户的回答让我沮丧："Paul，这是你的代码，你去年写的。"于是感到尴尬。

这是一个很好的教训：无论逻辑多么简单，都要添加注释。因为不论逻辑看起来多么合理，对下一个读它的人来说，就不一定那么合理了，尤其是几个月甚至几年之后。汲取这一简单事件的教训，我们就应记住：每个人都会留下一些东西，其他查询设计人员与程序员会记住你留给他们维护的程序。但他们最可能记住的是，你使他们的维护工作变得更困难，或者更容易。

T-SQL注释有两种形式：块注释和行内注释。块注释常常用于头块，头块是脚本对象(如存储过程或者用户自定义函数)之前的一个正式的文本块。头块应符合标准格式，包含如下信息：

脚本对象的名字

设计人员与程序员的名字

创建日期

修改日期与注解

对象的作用和调用方式等信息

验证测试与批准注解

块注释以斜杠和至少一个星号(/*)开始，并以一个星号和一个斜杠(*/)结束。中间的所有文本都是注释，查询解析器会忽略它们。头块注释不需要太复杂，但应保持一致。下面的这个头块注释被添加在一个插入产品记录的存储过程之前：

 

  1. /**************************************************  
  2. *   spInsProduct - Inserts product records  
  3. *  
  4. *   Accepts ProductName, StandardPrice, 
    QtyInStock, CategoryID  
  5. *   Returns new ProductID, Int 
  6. *  
  7. *   Created: 6-12-08 (Paul Turley)  
  8. *  
  9. *   Revisions:  
  10. *   7-10-08 - (Dan Wood)      Added MarkupPercent parameter  
  11. *   7-12-08 - (Paul Turley)   Changed MarkupPercent
    parameter data type from   
  12. *                                int to decimal(10,2)  
  13. **********************************************
    ***********************/ 

行内注释放在脚本体中，用于解释脚本的执行过程和流程。注释以两个连接符(--)开头，查询解析器会忽略该行后面的部分。行内注释可以放在可执行脚本的后面，也可以另起一行，如下所示：

  1. CREATE PROCEDURE spGetProductHistory  
  2. -- Define date parameters, set NULL defaults to 
    make parameters optional  
  3.    @StartDate datetime = NULL 
  4.   ,@EndDate datetime = NULL 
  5. AS 
  6. --Check date values. If NULL set default dates to
    cover entire product history  
  7.   IF @StartDate IS NULL         
  8.      SET @StartDate = '1900-01-01' 
  9.   IF @EndDate IS NULL 
  10.      SET @EndDate = GETDATE()  
  11.                    
  12.     -- Return all product history for defined time period  
  13.        SELECT PC.Name AS Category  
  14.              ,PSC.Name AS SubCategory  
  15.              ,P.Name AS ProductName  
  16.              ,SOH.OrderDate  
  17.              ,SOD.OrderQty  
  18. --           ,SOD.UnitPrice  
  19.        FROM   Sales.SalesOrderHeader AS SOH  
  20.        INNER JOIN Sales.SalesOrderDetail AS SOD   
  21.           ON SOH.SalesOrderID = SOD.SalesOrderID   
  22.        INNER JOIN Production.Product AS P   
  23.           ON SOD.ProductID = P.ProductID  
  24.        INNER JOIN Production.ProductSubCategory AS PSC  
  25.           ON P.ProductSubCategoryID = PSC.ProductSubCategoryID   
  26.        INNER JOIN Production.ProductCategory AS PC  
  27.           ON PSC.ProductCategoryID = PC.ProductCategoryID  
  28.        WHERE SOH.OrderDate BETWEEN @StartDate AND @EndDate  
  29.     ORDER BY PC.Name 
  30.         ,PSC.Name 
  31.         ,P.Name 

在这个例子中，程序员用注释告诉阅读者该脚本的作用。如果有疑问，就加上一个注释；如果没有疑问，也可以加上一个注释-不要担心注释太多。诚然，有些脚本不加注释也容易理解，但是请不要冒险。不要认为：不用现在就给代码添加注释，可以以后再加。也许你比我更有原则，不过我坚持认为在编码时如果不写注释，工作就不算完成。实际上，许多图书在提到编写优秀的程序代码时，都坚持认为在没有编写任何代码前，就应编写注释，这有时被称为"伪代码"。在编写了几个注释块和行内注释后，才开始填充代码。以前面的例子为例，在编写实际的代码之前，注释应如下所示：

  1. CREATE PROCEDURE spGetProductHistory  
  2. -- Define date parameters, set NULL defaults
    to make parameters optional  
  3. --Check date values. If NULL set default dates 
    to cover entire product history  
  4.  
  5.     -- Return all product history for defined time period 

行内注释的另一个重要作用是为自己和其他开发人员提供临时的开发注解。在第一次调试脚本时，肯定最关心核心功能能否正常工作。除了基本的逻辑以外，工作区域内的问题、错误处理以及不常见的状态，与代码在理想情况下能正常工作相比，通常是次要的。在考虑所有这些次要的因素时，应会做一些注解，包括要做的项目和备忘录，以便回过头来添加清理代码，精化功能。

另外，有时在建立大型脚本时，希望禁止执行某些代码。但一一找出这些错误的代码或者删除这些代码是不必要的，只需要注释掉它们即可。注释掉代码有两种方式：块注释和行内注释。行内注释一般是注释掉一部分代码的首选方式。SQL Server Management Stuido提供了键盘和按钮快捷方式来注释掉突出显示的代码。只需突出显示要禁用或注释掉的代码部分，再单击SQL Editor工具栏上的Comment Selection按钮即可，如图4-1所示。如果使用快捷键，则应突出显示代码部分，按下Ctrl+K或Ctrl+C组合键。要取消对选中代码的注释，可以单击Uncomment按钮，或者按下Ctrl+K、Ctrl+U组合键。

 
（点击查看大图）图  4-1
【责任编辑：云霞 TEL：（010）68476606】

posted on 2017-03-28 11:28  水碧  阅读(250)  评论(0)  编辑  收藏  举报

导航