建站
咨詢
售后
建站咨詢
新聞中心
1.6 注釋規(guī)范
注釋規(guī)范是判斷一個開發(fā)人員優(yōu)劣和成熟度的重要指標。一個優(yōu)秀的研發(fā)人員必然是經(jīng)過深思熟慮然后才洋洋灑灑妙筆生花的，注釋的書寫體現(xiàn)了一個人思考問題的全過程和步驟；話又說回來，就算代碼寫的爛，只要注釋寫的好，至少也會給人以良好的感覺；同時也能造福后人，不是么？呵呵。
建網(wǎng)站原本是網(wǎng)站策劃師、網(wǎng)絡(luò)程序員、網(wǎng)頁設(shè)計師等，應(yīng)用各種網(wǎng)絡(luò)程序開發(fā)技術(shù)和網(wǎng)頁設(shè)計技術(shù)配合操作的協(xié)同工作。成都創(chuàng)新互聯(lián)專業(yè)提供網(wǎng)站制作、成都做網(wǎng)站,網(wǎng)頁設(shè)計,網(wǎng)站制作(企業(yè)站、響應(yīng)式網(wǎng)站、電商門戶網(wǎng)站)等服務(wù),從網(wǎng)站深度策劃、搜索引擎友好度優(yōu)化到用戶體驗的提升,我們力求做到極致!
規(guī)則1.6. 1
一般情況下，源程序有效注釋量必須在30% 左右。
說明：注釋的原則是有助于對程序閱讀理解，在該加的地方都加了，注釋不宜太多也不能太少，注釋語言須準確、易懂、簡潔、精煉。
規(guī)則1.6. 2
統(tǒng)一文件頭的注釋.
主要是對相關(guān)過程、函數(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
對程序分支必須書寫注釋。
說明：這些語句往往是程序?qū)崿F(xiàn)某一特定功能的關(guān)鍵，對于維護人員來說，良好的注釋幫助更好的理解程序，有時甚至優(yōu)于看設(shè)計文檔。
在程序塊的結(jié)束行右方加注釋，以表明程序塊結(jié)束。
規(guī)則1.6. 6
注釋應(yīng)與其描述的代碼相似，對代碼注釋應(yīng)放在其上方或右方( 對單條語句的注釋) 相近位置，不可放在下面。
注釋與所描述的內(nèi)容進行同樣的縮排。
注釋上面的代碼應(yīng)空行隔開。
建議1.6. 7
注釋用中文書寫
有一次，同事寫了一個900 行的存儲過程，里面定義了十幾個游標以進行遍歷，這個存儲過程缺乏注釋，執(zhí)行一次居然要一天一夜，已經(jīng)達到了無法容忍的地步。
因為缺乏注釋，我花了整整一天的時間來對該存儲過程進行分析，然后用了半天時間來進行改寫和調(diào)試。
其實很簡單定義，我定義了一些對應(yīng)的臨時表，把游標遍歷替換成SQL 的集合操作，把整個的一個大事務(wù)分割成若干小事務(wù)，只是修改了部分代碼，結(jié)果執(zhí)行時間就變成了短短的3 分鐘。
當然游標也并非不可觸及的，既然存在就有他存在的理由。
當前題目：數(shù)據(jù)庫編程之注釋規(guī)范
文章來源：http://m.5511xx.com/article/cdhciso.html
