數據庫編程之注釋規范
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 分鐘。
當然游標也并非不可觸及的，既然存在就有他存在的理由。
【編輯推薦】
