---

 

       好的注釋規(guī)范會讓你的程序更易讀，也讓你的程序和代碼更專業(yè)，并且方便你和整個(gè)團(tuán)隊(duì)合作開發(fā)。是團(tuán)隊(duì)開發(fā)必須掌握的一項(xiàng)規(guī)則。

 

 

 

---

 
       對于變量的注釋緊跟在變量的后面說明變量的作用。原則上對于每個(gè)變量應(yīng)該注釋，但對于意義非常明顯的變量，如：i,j等循環(huán)變量可以不注釋。
例如： Dim strFormName As String  ‘保存控件所在窗體的名稱。

 

請注意：

對于非通用的變量，在定義時(shí)最好加以詳細(xì)注釋說明，甚至加上示例或圖解。

 

變量定義盡可能放在函數(shù)或子程序的最開始處，統(tǒng)一管理。
　

 

---

 

       對于函數(shù)，應(yīng)該從“函數(shù)名稱”、“功能描述”，“輸入?yún)?shù)”，“返回值”、“主要思路”、“調(diào)用方法”、“相關(guān)函數(shù)”、“兼容性”、“作者”、“創(chuàng)建/修改日期”十個(gè)方面用如下格式注釋，如果需要，還可加上“使用注意”、“參考資料”、“圖解”等注釋項(xiàng)

 

 
'=================================================================
'-函數(shù)名稱:         gprocInitXpStyle
'-功能描述:         初始化窗體的XP風(fēng)格
'-輸入?yún)?shù):         參數(shù)1:rstrFrmName String 窗體名稱
'-返 回 值:         無
'-調(diào)用方法:         gprocInitXpStyle "frmMainMenu"
'-相關(guān)函數(shù):         gfuncSetMouseMove gfuncSetMouseDown gfuncSetMouseUp
'-主要思路:         在窗體加載或打開時(shí)設(shè)置所有控件的的鼠標(biāo)事件從而實(shí)現(xiàn)XP風(fēng)格
'-使用注意:      只適用Label TextBox CommandButton ComboBox OptionButton CheckBox
'-兼 容 性:         97,2000,XP compatible
'-參考文獻(xiàn):
'-作    者:         王宇虹  修改：王宇虹
'-創(chuàng)建日期;         2002-08-26  更新日期: 2002-08-28
'-圖    解:
'===================================================================
 

 

 

 

有些函數(shù)，部分參數(shù)為可選參數(shù)，則需加說明，對于某些意義不明確的參數(shù)還要做詳細(xì)說明（例如：以角度作為參數(shù)時(shí)，要說明該角度參數(shù)是以弧度（PI）,還是以度為單位）。等等。②

如果你的函數(shù)參考了別人的代碼，則需特別指出原作者及相關(guān)鏈接。尊重別人的成果

函數(shù)內(nèi)各功能模塊，如：循環(huán)、流程的各分支等，盡可能多地加以注釋。

在注釋中應(yīng)該記錄函數(shù)修改的日期，并詳細(xì)說明函數(shù)的主要實(shí)現(xiàn)思路、特別要注明自己的一些獨(dú)到想法，如果有必要則應(yīng)該寫明對想法產(chǎn)生的來由。

在注釋中詳細(xì)注明函數(shù)的適當(dāng)調(diào)用方法，對于返回值的處理方法等。在使用注意中要強(qiáng)調(diào)調(diào)用時(shí)的一些特別需要注意的事項(xiàng)，以及調(diào)用可能出現(xiàn)的后果或可能出錯(cuò)的情況。

應(yīng)保留函數(shù)創(chuàng)建日期及中間每次修改的日期。

對函數(shù)注釋開始到函數(shù)命名之間應(yīng)該有一組用來標(biāo)識的特殊字符串。

如果算法比較復(fù)雜，或算法中的變量定義與位置有關(guān)，則要求對變量的定義進(jìn)行圖解。對難以理解的算法能圖解盡量圖解。

 

模塊和類模塊的注釋

 

'====================================================================
'-（類）模塊名稱:   modPrint
'-（類）模塊描述:     有關(guān)打印和預(yù)覽以及印頁面設(shè)置的一些公用函數(shù)和子程序
'-主要函數(shù)與事件:   
'
'-版  本:          模塊的版本號，最后完成日期。
'-參考文獻(xiàn):         
'-測試用例:
'-使用注意:         
'-兼容性:           97,2000,XP compatible
'-作者:             王宇虹，改進(jìn)：王宇虹
'-修改::          說明對模塊的修改內(nèi)容、修改原因以及修改日期
'====================================================================

 

①、 每個(gè)模塊應(yīng)盡量只包含某一類型的代碼，以方便分類管理和方便注釋。

②、 主要的函數(shù)和事件應(yīng)該在模塊注釋中予以注明，這樣別人就不必尋找所有模塊的代碼就可找到自己需要的函數(shù)在哪個(gè)模塊。
③、 參考文獻(xiàn)只需簡要說明主要的參考文獻(xiàn)，而具體哪個(gè)函數(shù)參考哪些文獻(xiàn)則在函數(shù)的注釋中再予以說明。

 

 

 

---

 

 

       對ACCESS中的對象，包括表（表的字段）、窗體、報(bào)表、模塊、數(shù)據(jù)頁、宏等做一個(gè)對象級的說明，在未打開這個(gè)對象之前，讓別人知道這個(gè)對象包含什么內(nèi)容及處理哪些功能。

 

 

 

在這個(gè)圖中對每個(gè)模塊和類模添加了一個(gè)簡要的說明，一旦你的系統(tǒng)越來越大，對象越來越多的時(shí)候，這些說明能讓你更快地找到你需要的對象。

 

 

 

 

如果你平時(shí)與你的同事協(xié)同進(jìn)行開發(fā)，而且經(jīng)常需要相互之間導(dǎo)入導(dǎo)出程序或?qū)ο?，那么在?dǎo)入導(dǎo)出過程中，可能這些說明會丟失，為此，我專門寫了一個(gè)工具（說明導(dǎo)入導(dǎo)出工具），它可以幫助你單獨(dú)將這些對象的說明導(dǎo)入到一個(gè)數(shù)據(jù)表中，然后在另一個(gè)數(shù)據(jù)庫中導(dǎo)入它，當(dāng)然，這個(gè)工具還包括了其它一些非常有用的功能，如果你需要這個(gè)工具或?qū)λ信d趣，可到www.access-cn.com中下載

 

說明里的文字的第一個(gè)字符也可按照一定的規(guī)律來編寫，以方便以后的排序和索引

 

 

 

 

---

 

 

在代碼當(dāng)前行的后面，通常會做一些必要的注釋，如：

Static sstrCtrNameLast As String '靜態(tài)變量 用來保存最近一次移動過的控件名稱

Dim ctr As Control               '臨時(shí)變量 用來定義當(dāng)前控件和最近一次移動過的控件

Dim frm As Form                 '臨時(shí)變量 用來定義當(dāng)前的窗體