原則1: 關于函數注釋 ?說明 關于使用(某函數)方法的注釋： (頭文件中)函數聲明之前，要給出恰當的注釋，從而讓使用者無需了解實現細節就能夠快速獲得足夠的信息來使用該函數：同時這些信息又是精煉的，沒有不相關的內容。 關于(某函數)實現的注釋： 在函數實現之前，要給出和實現有關的足夠而精煉的注釋信息。 ?例子 /***************************************************************** *函 數 名：XXXXXXXX *功 能：XXXXXXXXX *入口參數： *返 回 值：總重量 *作者：XXX 日期：2001/XX/XX *模塊標識：SYSXXX-SUBXXX-MXXX ****************************************************************** *修改記錄： 修改執行人： 修改日期：2001/XX/XX 修改說明：………… * *****************************************************************/ 注意：對于軟件外包項目，紅色部分不能出現，因為軟件的產權不屬于你。 原則2: 關于注釋頻率 ?說明 經驗表明：注釋占代碼總量的30%左右，這樣一個注釋量能保證既清楚表達了程序員的意思，又不至于過分占用程序員的時間。 原則3: 注釋是完善你的代碼，而不是重復你的代碼 ?說明 注釋不應包含代碼本身顯而易見的信息，而應給出其他有用的信息。這些內容應是重要的，否則不如不加。 ?例子 // 這種注釋沒有用處 index++; // Increment index 原則4: 注釋中的要盡量用通用術語 原則5:修改代碼時，相應的注釋要及時更新 原則6: 注釋不要嵌套 ?例子 / * if (verbosity)0) { / * 這是嵌套注釋* / cerr<<"Opening file<"<<filename<<">"<<end1; } * / 原則7: 區分段落注釋和單行注釋 ?說明 注釋分段落和單行兩大類： 1)段落注釋用來說明一段代碼，因而要放在該段代碼之前。通常，此類注釋較長(超過一行)，建議用戶*/風格。 2)單行注釋用來說明一句代碼，通常放在該代碼之后(行未注釋)。建議用//風格。 段落注釋用橫線上下框住（見例子或附錄的大段代碼），目的是一目了然地將代碼和注釋區分出來，這樣有利于代碼和注釋的閱讀。 ?“戰略性”注釋的例子(格式) / * * This is "strategic" comment * used for block comments. * / 原則8: 避免在代碼行的末尾添加注釋；行尾注釋使代碼更難閱讀。不過在批注變量聲明時，行尾注釋是合適的；在這種情況下，將所有行尾注釋在公共制表位處對齊。 ?說明 一般從第46個字符位置開始：不同文件中可以不同，但同一個文件中最好保持一致。 原則9: 單獨的注釋行和被注釋語句縮進相同的空格 原則10: 減少不必要的單獨占一行的注釋 原則11: 對每個引用的頭文件給出行末注釋 ?例子 #include〈iostream.h〉 // use cout，etc. #include〈pthread.h〉 // use POSIX thread library #include"ZDebug.hpp" // use macro Z_DEBUG() #include"ZErrLog.hpp" // use macro Z_L0G_...() #include"ZMutex.hpp" // use class Z_Mutex_T 原則12: 對每個空循環體給出確認性注釋 ?例子 while (str[ctr++]!=EOS) { // This is an empty body } 原則13: 避免雜亂的注釋，應該使用空白將注釋同代碼分開。 原則14: 避免在塊注釋的周圍加上印刷框，難于維護。 原則15: 在部署發布之前，移除所有臨時或無關的注釋，以避免在日后的維護工作中產生混亂。 原則16: 如果需要用注釋來解釋復雜的代碼節，請檢查此代碼以確定是否應該重寫它。盡一切可能不注釋難以理解的代碼，而應該重寫它。 原則17: 在編寫注釋時使用完整的句子。注釋應該闡明代碼，而不應該增加多義性。 原則18: 在編寫代碼時立刻注釋。 原則19: 避免多余的或不適當的注釋。 原則20: 使用注釋來解釋代碼的意圖。它們不應作為代碼的聯機翻譯。 原則21: 注釋代碼中不十分明顯的任何內容。 原則22: 為了防止問題反復出現，對錯誤修復和解決方法代碼總是使用注釋，尤其是在團隊環境中。 原則23: 對由循環和邏輯分支組成的代碼使用注釋。這是幫助源代碼讀者的主要方面。 原則24: 在整個應用程序中，使用具有一致的標點和結構的統一樣式來構造注釋。 原則25: 用空白將注釋同注釋分隔符分開。 原則26: 在所有的代碼修改處加上修改標識的注釋。 原則27: 為了是層次清晰，在閉合的右花括號后注釋該閉合所對應的起點。 namespace Langchao.Procument.Web { } // namespace Langchao.Procument.Web