讓你提前認識軟體開發(26)：資料庫腳本的注釋

第2部分 資料庫SQL語言

資料庫腳本的注釋

1. 概述

        注釋在程式語言的編寫中占有非常重要的地位。優美的、得當的注釋不僅有助于研發人員了解程式，還能夠提高程式設計效率(進而提高辦事效率)。

        但是，可能是由于工作比較忙的緣故，許多開發人員不重視注釋的書寫，這也導緻了項目交接的時候，其他開發人員了解程式困難，甚至不知道程式到底要做什麼事情。是以，良好注釋的書寫是對一個開發人員的基本要求，大家一定要重視。

        對于腳本的注釋，建議大家一律采用英文，這樣可以展現出國際化、專業性與規範性。

2. 資料庫腳本檔案頭部的注釋

        很多腳本檔案都沒有頭部的注釋，大家認為它不重要。但作者認為一定要把這部分内容加上，這樣為以後追蹤版本資訊提供了友善。

        在檔案頭部的注釋中，要包括版權、資料庫類型、建立日期、作者、修改記錄等資訊，可以采用以下的樣式：

--*********************************************************************

-- copy right (C)2014, company name.

-- DB Type: XXX

-- Content: XXX

-- Created: YYYY.MM.DD

-- Modify1: The name of the author

-- Date1: YYYY.MM.DD

-- version1: The original version of the product

-- Modify2: The name of who modified the file

-- Date2: YYYY.MM.DD

-- version2: The updated version of the product

--**********************************************************************

3. 資料庫腳本檔案摘要資訊的注釋

        在頭部注釋之後，不要馬上就開始建立表及存儲過程，而應該有一個摘要。如果是建表腳本，摘要就是該檔案中包括的表的名稱和用途；如果是建立存儲過程的腳本，摘要就是該檔案中包括的存儲過程的名稱和用途。這個摘要可以起到索引的作用，幫助開發人員了解腳本檔案的主要内容。

        摘要資訊的注釋可以采用以下的樣式：

--********* XXX(Version)DataBase Table Creating*********

--*  1    table1                : description1

--*  2    table2                : description2

--*  3    table3                : description3

    . . . . . .

--***************************************************

4. 表或存儲過程開頭處的注釋

        在表或存儲過程的開頭處添加注釋，可以起到友善定位、易于查閱的作用。可以采用以下的樣式：

-- XXX(The name of the table or procedure, and what it is used for)

The definition of the table or procedure

5. 表的各字段之後的注釋

        在定義了一個表的各字段之後，需要對每個字段進行注釋，以友善研發人員了解其作用，避免猜測和錯誤了解。這樣，使用起來也會得心應手。

        表的定義及字段注釋可以采用以下的樣式：

create table tb_XXX

 (

    AAA               int                                   not null,          -- description1

    BBB              varchar(256)                 not null,          -- description2

    CCC              int default(0)                        null,          -- description3

    DDD             varchar(256)  default('''')   null,         -- description4

)

6. 存儲過程的注釋

        一般說來，存儲過程包括的SQL語句比較多，是以注釋也會比較的複雜。即便是這樣，在一些關鍵語句的地方，一定要有注釋，否則其他開發人員閱讀起來就會比較費勁。

       存儲過程的編寫及注釋可以采用以下的樣式(以Sybase資料庫中的文法為例)：

create procedure pr_XXX

    @AAA          varchar(30),        -- description1

    @BBB          int,                       -- description2

as

begin

declare

    @CCC          int,                       -- description3

@DDD          varchar(100),        -- description4

   . . . . . .

    -- YYY(name) add YYYYMMDD for ZZZ begin

    -- YYY(name) add YYYYMMDD for ZZZ end

    statement1                    -- YYY add YYYYMMDD description5

    statement2                    -- YYY modify YYYYMMDD description6

     . . . . . .

    statement3                    -- YYY delete YYYYMMDD description7

    statement4                    -- description8(important statement)

end

7. 有關注釋的一些規則和建議

(1) 統一使用“--”進行注釋(不要使用“/* */進行注釋”)。

(2) 腳本檔案頭部必須進行注釋。

(3) 每段完成一定功能的腳本前(如建立資料表、存儲過程、任務、插入預設記錄等)，均應有注釋說明。

(4) 建立資料表中每個字段後應有注釋，說明字段含義，有些還需要說明取值範圍等。

(5) 建立存儲過程和函數中每個輸入輸出參數後應有注釋，說明參數含義，有些還需要說明取值範圍等。

(6) 對分支語句(包括條件分支)、循環語句等要編寫注釋。

(7) 保證代碼和注釋的一緻性。修改代碼同時修改相應的注釋，不再有用的注釋要删除。

(8) 注釋應與其描述的代碼相近，對代碼的注釋應放在其上方或右方(對資料表中字段和存儲過程參數的注釋)相鄰位置，不可放在下面，如放于上方則需與其上面的代碼用空行隔開。

(9) 注釋與所描述代碼進行同樣的縮排。

(10) 中文版本的注釋統一使用中文描述，海外版本的注釋統一使用英文描述。

(11) 通過對函數或過程、變量等正确的命名以及合理地組織代碼結構，使代碼成為自注釋的。

(12) 盡量避免在注釋中使用縮寫，特别是不常用縮寫。

8. 總結

        注釋的作用是錦上添花，不恰當的注釋不但不能夠起到應有的作用，反而有可能讓人産生誤解。是以，我們在添加腳本檔案注釋的時候，一定要遵循簡單、清晰、明了、通俗易懂的原則。