資料庫編程之注釋規範

1.6 注釋規範
注釋規範是判斷一個開發人員優劣和成熟度等級的重要指標。一個優秀的研發人員必然是經過深思熟慮然後才洋洋洒洒妙筆生花的，注釋的書寫體現了一個人思考問題的全過程和步驟；話又說回來，就算代碼寫的爛，只要注釋寫的好，至少也會給人以良好的感覺；同時也能造福後人，不是嗎？呵呵。

規則1.6. 1

一般情況下，來源程式有效注釋量必須在30% 左右。

說明：注釋的原則是有助於對程式閱讀理解，在該加的地方都加了，注釋不宜太多也不能太少，注釋語言須準確、易懂、簡潔、精鍊。

規則1.6. 2

統一檔案頭的注釋.

主要是對相關過程、函數進行功能性描述、歷程記錄、以及入參出參說明

對預存程序、函數的任何修改，都需要在注釋後添加修改人、修改日期及修改原因等修訂說明。

/***********************************************************

名稱: sp_xxx

功能描述：

歷程記錄：

版本號碼 編輯時間 編輯人 修改描述

1.0.0 2010-01-01 John 1 、建立此預存程序

1.0.1 2010-02-01 Sandy 2 、增加傳入參數

入參出參描述：

iparameter1 IN VARCHAR2(20) 傳入參數1

iparameter2 IN VARCHAR2(20) 傳入參數2

iparameter1 OUT VARCHAR2(20) 傳入參數1

iparameter2 OUT VARCHAR2(20) 傳入參數2

傳回值描述：( 主要針對函數)

0 - Success

1 - normal fail

***********************************************************/

規則1.6. 3

所有變數定義需要加註釋，說明該變數的用途和含義。

規則1.6. 4

注釋內容要清晰、明了、含義準確，防止注釋二義性

在代碼的功能、意圖層次上進行注釋，提供有用、額外的資訊。

避免在一行代碼或運算式的中間插入注釋。

盡量使用”-- ”進行注釋；行章節附註釋須使用”-- ”。

規則1.6. 5

對程式分支必須書寫注釋。

說明：這些語句往往是程式實現某一特定功能的關鍵，對於維護人員來說，良好的注釋協助更好的理解程式，有時甚至優於看設計文檔。

在程式塊的結束行右方加註釋，以表明程式塊結束。

規則1.6. 6

注釋應與其描述的代碼相似，對代碼注釋應放在其上方或右方( 對單條語句的注釋) 相近位置，不可放在下面。

注釋與所描述的內容進行同樣的縮排。

注釋上面的代碼應空行隔開。

建議1.6. 7

注釋用中文書寫

有一次，同事寫了一個900 行的預存程序，裡面定義了十幾個遊標以進行遍曆，這個預存程序缺乏注釋，執行一次居然要一天一夜，已經達到了無法容忍的地步。

因為缺乏注釋，我花了整整一天的時間來對該預存程序進行分析，然後用了半天時間來進行改寫和調試。

其實很簡單定義，我定義了一些對應的暫存資料表，把遊標遍曆替換成SQL 的集合操作，把整個的一個大事務分割成若干小事務，只是修改了部分代碼，結果執行時間就變成了短短的3 分鐘。

當然遊標也並非不可觸及的，既然存在就有他存在的理由。