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