數(shù)據(jù)庫編程之注釋規(guī)范
1.6 注釋規(guī)范
注釋規(guī)范是判斷一個開發(fā)人員優(yōu)劣和成熟度的重要指標。一個優(yōu)秀的研發(fā)人員必然是經(jīng)過深思熟慮然后才洋洋灑灑妙筆生花的，注釋的書寫體現(xiàn)了一個人思考問題的全過程和步驟；話又說回來，就算代碼寫的爛，只要注釋寫的好，至少也會給人以良好的感覺；同時也能造福后人，不是么？呵呵。
規(guī)則1.6. 1
一般情況下，源程序有效注釋量必須在30% 左右。
說明：注釋的原則是有助于對程序閱讀理解，在該加的地方都加了，注釋不宜太多也不能太少，注釋語言須準確、易懂、簡潔、精煉。
規(guī)則1.6. 2
統(tǒng)一文件頭的注釋.
主要是對相關過程、函數(shù)進行功能性描述、修訂記錄、以及入?yún)⒊鰠⒄f明
對存儲過程、函數(shù)的任何修改，都需要在注釋后添加修改人、修改日期及修改原因等修訂說明。
/***********************************************************
名稱: sp_xxx
功能描述：
修訂記錄：
版本號 編輯時間 編輯人 修改描述
1.0.0 2010-01-01 John 1 、創(chuàng)建此存儲過程
1.0.1 2010-02-01 Sandy 2 、增加傳入?yún)?shù)
入?yún)⒊鰠⒚枋觯?/p>
iparameter1 IN VARCHAR2(20) 傳入?yún)?shù)1
iparameter2 IN VARCHAR2(20) 傳入?yún)?shù)2
iparameter1 OUT VARCHAR2(20) 傳入?yún)?shù)1
iparameter2 OUT VARCHAR2(20) 傳入?yún)?shù)2
返回值描述：( 主要針對函數(shù))
0 - Success
1 - normal fail
***********************************************************/
規(guī)則1.6. 3
所有變量定義需要加注釋，說明該變量的用途和含義。
規(guī)則1.6. 4
注釋內(nèi)容要清晰、明了、含義準確，防止注釋二義性
在代碼的功能、意圖層次上進行注釋，提供有用、額外的信息。
避免在一行代碼或表達式的中間插入注釋。
盡量使用”-- ”進行注釋；行尾注釋須使用”-- ”。
規(guī)則1.6. 5
對程序分支必須書寫注釋。
說明：這些語句往往是程序實現(xiàn)某一特定功能的關鍵，對于維護人員來說，良好的注釋幫助更好的理解程序，有時甚至優(yōu)于看設計文檔。
在程序塊的結束行右方加注釋，以表明程序塊結束。
規(guī)則1.6. 6
注釋應與其描述的代碼相似，對代碼注釋應放在其上方或右方( 對單條語句的注釋) 相近位置，不可放在下面。
注釋與所描述的內(nèi)容進行同樣的縮排。
注釋上面的代碼應空行隔開。
建議1.6. 7
注釋用中文書寫
有一次，同事寫了一個900 行的存儲過程，里面定義了十幾個游標以進行遍歷，這個存儲過程缺乏注釋，執(zhí)行一次居然要一天一夜，已經(jīng)達到了無法容忍的地步。
因為缺乏注釋，我花了整整一天的時間來對該存儲過程進行分析，然后用了半天時間來進行改寫和調(diào)試。
其實很簡單定義，我定義了一些對應的臨時表，把游標遍歷替換成SQL 的集合操作，把整個的一個大事務分割成若干小事務，只是修改了部分代碼，結果執(zhí)行時間就變成了短短的3 分鐘。
當然游標也并非不可觸及的，既然存在就有他存在的理由。
【編輯推薦】
