【文章內(nèi)容簡(jiǎn)介】 什么要那么做，而不是怎么去做。 1）一般情況下，源程序有效注釋量必須在20％以上。注釋的原則是有助于對(duì)程序的閱讀理解，在該加的地方都加，注釋不宜太多也不能太少，注釋語(yǔ)言必須準(zhǔn)確、易懂、簡(jiǎn)潔； 2）注釋格式盡量統(tǒng)一，建議使用“/* ?? */”； 3）說(shuō)明性文件（、.inc文件等）頭部應(yīng)進(jìn)行注釋?zhuān)⑨尡仨毩谐觯喊鏅?quán)說(shuō)明、版本號(hào)、生成日期、作者、內(nèi)容、功能、與其它文件的關(guān)系等，頭文件的注釋中還應(yīng)有函數(shù)功能簡(jiǎn)要說(shuō)明； 4）源文件頭部應(yīng)進(jìn)行注釋?zhuān)谐觯喊鏅?quán)說(shuō)明、版本號(hào)、生成日期、作者、模塊功能、主要函數(shù)及其功能等； 5）函數(shù)頭部應(yīng)進(jìn)行注釋?zhuān)谐觯汉瘮?shù)功能、輸入?yún)?shù)、輸出參數(shù)、返回值等；6）邊寫(xiě)代碼邊注釋?zhuān)薷拇a同時(shí)修改相應(yīng)的注釋?zhuān)员ＷC注釋與代碼的一致性；7）避免在注釋中使用縮寫(xiě)，特別是非常用的縮寫(xiě)。如無(wú)法避免，應(yīng)對(duì)縮寫(xiě)進(jìn)行必要的說(shuō)明； 8）注釋?xiě)?yīng)與其描述的代碼相近，對(duì)代碼的注釋?xiě)?yīng)放在其上方或右方（對(duì)單條語(yǔ)句的注釋?zhuān)┫噜徫恢?，如放于上方則需與其上面的代碼用空行隔開(kāi)； 9）變量、常量、宏的注釋有時(shí)也是必須的，應(yīng)放在其上方相鄰位置或右方； 10）數(shù)據(jù)結(jié)構(gòu)聲明(包括數(shù)組、結(jié)構(gòu)、類(lèi)、枚舉等)，如果其命名不是充分自注釋的，必須加以注釋。對(duì)數(shù)據(jù)結(jié)構(gòu)的注釋?xiě)?yīng)放在其上方相鄰位置，對(duì)結(jié)構(gòu)中的每個(gè)域的注釋放在此域的右方； 11）全局變量要有較詳細(xì)的注釋?zhuān)▽?duì)其功能、取值范圍、哪些函數(shù)或過(guò)程存取它以及存取時(shí)注意事項(xiàng)等的說(shuō)明； 12）將注釋與其上面的代碼用空行隔開(kāi)，注釋與所描述內(nèi)容進(jìn)行同樣的縮排； 13）對(duì)變量的定義和分支語(yǔ)句（條件分支、循環(huán)語(yǔ)句等）必須編寫(xiě)注釋。這些語(yǔ)句往往是程序?qū)崿F(xiàn)某一特定功能的關(guān)鍵，對(duì)于維護(hù)人員來(lái)說(shuō)，良好的注釋幫助更好地理解程序，有時(shí)甚至優(yōu)于看設(shè)計(jì)文檔； 14）通過(guò)對(duì)函數(shù)或過(guò)程、變量、結(jié)構(gòu)等正確的命名以及合理地組織代碼的結(jié)構(gòu)，使代碼成為自注釋的，減少不必要的注釋?zhuān)?15）當(dāng)代碼段較長(zhǎng)，特別是多重嵌套時(shí)，在程序塊的結(jié)束行右方加注釋標(biāo)記，以表明某程序塊的結(jié)束； 16）建議注釋多使用中文，除非能用非常流利準(zhǔn)確的英文表達(dá)。 標(biāo)識(shí)符命名 1）標(biāo)識(shí)符的命名要清晰明了，有明確含義，同時(shí)使用完整的單詞或大家基本可以理解的縮寫(xiě)，避免使人產(chǎn)生誤解。較長(zhǎng)的單詞可取單詞的頭幾個(gè)字母形成縮寫(xiě)，一些單詞有大家公認(rèn)的縮寫(xiě)； 2）命名中若使用特殊約定或縮寫(xiě)，應(yīng)該在源文件的開(kāi)始之處，進(jìn)行必要的注釋說(shuō)明；3）命名風(fēng)格要自始至終保持一致； 4）對(duì)于變量命名，禁止取單個(gè)字符（如i、j、k...）。單個(gè)字符容易敲錯(cuò)，且編譯時(shí)又不易檢查出來(lái)。建議除了要有具體含義外，還能表明其變量類(lèi)型、數(shù)據(jù)類(lèi)型等，但i、j、k作局部循環(huán)變量是可以的； 5）命名規(guī)范必須與所使用的系統(tǒng)風(fēng)格保持一致，并在同一項(xiàng)目中統(tǒng)一。除非必要，不要用數(shù)字或較奇怪的字符來(lái)定義標(biāo)識(shí)符； 6）在同一軟件產(chǎn)品 begin / end create / destroy insert / delete add / delete get / release increment / decrement put / get lock / unlock open / close first / last min / max old / new start / stop next / previous send / receive show / hide source / target source / destination cut / paste up / down 8）除了特殊應(yīng)用，應(yīng)避免使用以下劃線(xiàn)開(kāi)始和結(jié)尾的定義。 可讀性 1）注意運(yùn)算符的優(yōu)先級(jí)，并用括號(hào)明確表達(dá)式的操作順序，避免使用默認(rèn)優(yōu)先級(jí)；2）避免使用不易理解的數(shù)字，用有意義的標(biāo)識(shí)來(lái)替代； 3）源程序中關(guān)系較為緊密的代碼應(yīng)盡可能相鄰，便于程序閱讀和查找； 4）不要使用難懂的技巧性很高的語(yǔ)句，除非很有必要時(shí)。程序的高效率并不等同于語(yǔ)句的高技巧，而在于算法。 變量與結(jié)構(gòu) 1）去掉沒(méi)必要的公共變量，以降低模塊間的耦合度； 2）仔細(xì)定義并明確公共變量的含義、作用、取值范圍及公共變量間的關(guān)系； 3）明確公共變量與操作此公共變量的函數(shù)或過(guò)程的關(guān)系，如訪(fǎng)問(wèn)、修改及創(chuàng)建等。這種關(guān)系的說(shuō)明可在注釋或文檔中描述； 4）當(dāng)向公共變量傳遞數(shù)據(jù)時(shí)，要十分小心，防止賦與不合理的值或越界等現(xiàn)象發(fā)生。若有必要應(yīng)進(jìn)行合法性檢查，以提高代碼的可靠性、穩(wěn)定性； 5）構(gòu)造僅有一個(gè)模塊或函數(shù)可以修改、創(chuàng)建，而其余有關(guān)模塊或函數(shù)只訪(fǎng)問(wèn)的公共變量，防止多個(gè)不同模塊或函數(shù)都可以修改、創(chuàng)建同一公共變量的現(xiàn)象； 6）使用嚴(yán)格形式定義的、可移植的標(biāo)準(zhǔn)數(shù)據(jù)類(lèi)型，盡量不要使用與具體硬件或軟件環(huán)境關(guān)系密切的變量； 7）結(jié)構(gòu)的功能要單一，是針對(duì)一種事務(wù)的抽象。結(jié)構(gòu)中的各元素應(yīng)代表同一事務(wù)的不同側(cè)面，而不應(yīng)把描述沒(méi)有關(guān)系或關(guān)系很弱的不同事務(wù)的元素放到同一結(jié)構(gòu)中； 8）不同結(jié)構(gòu)間的關(guān)系不要過(guò)于復(fù)雜，否則應(yīng)合為一個(gè)結(jié)構(gòu)； 9）仔細(xì)設(shè)計(jì)結(jié)構(gòu)中元素的布局與排列順序，使結(jié)構(gòu)容易理解、節(jié)省占用空間，并減少引起誤用的現(xiàn)象； 10）結(jié)構(gòu)的設(shè)計(jì)要盡量考慮向前兼容和以后的版本升級(jí)，并為某些未來(lái)可能的應(yīng)用保留余地； 11）留心具體語(yǔ)言及編譯器處理不同數(shù)據(jù)類(lèi)型的原則及有關(guān)細(xì)節(jié)； 12）編程時(shí)，要注意數(shù)據(jù)類(lèi)型的強(qiáng)制轉(zhuǎn)換。對(duì)編譯系統(tǒng)默認(rèn)的數(shù)據(jù)類(lèi)型轉(zhuǎn)換要有充分的認(rèn)識(shí)，盡量減少?zèng)]有必要的數(shù)據(jù)類(lèi)型默認(rèn)轉(zhuǎn)換與強(qiáng)制轉(zhuǎn)換，合理地設(shè)計(jì)數(shù)據(jù)并使用自定義數(shù)據(jù)類(lèi)型，避免數(shù)據(jù)間進(jìn)行不必要的類(lèi)型轉(zhuǎn)換； 13）對(duì)自定義數(shù)據(jù)類(lèi)型進(jìn)行恰當(dāng)命名，使它成為自描述性的，以提高代碼可讀性，但要注意其命名方式在同一產(chǎn)品中的統(tǒng)一。 函數(shù)與過(guò)程 1）設(shè)計(jì)高扇入、合理扇出（小于7）的函數(shù)。較良好的軟件結(jié)構(gòu)通常是頂層函數(shù)的扇出較高，中層函數(shù)的扇出較少，而底層函數(shù)則扇入到公共模塊中； 2）函數(shù)的規(guī)模盡量限制在200行以?xún)?nèi)，不包括注釋和空格行； 3）對(duì)所調(diào)用函數(shù)的錯(cuò)誤返回碼要仔細(xì)、全面地處理； 4）在同一項(xiàng)目組應(yīng)明確規(guī)定對(duì)接口函數(shù)參數(shù)的合法性檢查應(yīng)由函數(shù)的調(diào)用者負(fù)責(zé)還是由接口函數(shù)本身負(fù)責(zé)，缺省是由函數(shù)調(diào)用者負(fù)責(zé)； 5）防止將函數(shù)的參數(shù)作為工作變量。對(duì)必須改變的參數(shù)，最好先用局部變量代之，再將該局部變量的內(nèi)容賦給該參數(shù)； 6）一個(gè)函數(shù)僅完成一件功能，不要設(shè)計(jì)多用途的函數(shù)。函數(shù)名應(yīng)準(zhǔn)確描述函數(shù)的功能；7）函數(shù)的功能應(yīng)該是可以預(yù)測(cè)的，也就是說(shuō)只要輸入數(shù)據(jù)相同就應(yīng)產(chǎn)生同樣的輸出；8）避免設(shè)計(jì)多參數(shù)函數(shù)，不使用的參數(shù)從接口中去掉，減少函數(shù)間接口的復(fù)雜度；9）非調(diào)度函數(shù)應(yīng)減少或防止控制參數(shù)，盡量只使用數(shù)據(jù)參數(shù)，防止函數(shù)間的控制耦合；10）檢查函數(shù)所有參數(shù)輸入與非參數(shù)輸入的有效性； 11）在編程時(shí)，經(jīng)常遇到在不同函數(shù)中使用相同的代碼，許多開(kāi)發(fā)人員都愿把這些代碼提出來(lái)，并構(gòu)成一個(gè)新函數(shù)。若這些代碼關(guān)聯(lián)較大并且是完成一個(gè)功能的，那么這種構(gòu)造是合理的，否則這種構(gòu)造將產(chǎn)生隨機(jī)內(nèi)聚的函數(shù)； 12）功能不明確且較小的函數(shù)，特別是僅有一個(gè)上級(jí)函數(shù)調(diào)用它時(shí)，應(yīng)考慮把它合并到上級(jí)函數(shù)中，而不必單獨(dú)存在； 13）減少函數(shù)本身或函數(shù)間的遞歸調(diào)用。除非為某些算法或功能的實(shí)現(xiàn)方便，應(yīng)減少?zèng)]必要的遞歸調(diào)用； 14）仔細(xì)分析模塊的功能及性能需求，并進(jìn)一步細(xì)分，若有必要畫(huà)出有關(guān)數(shù)據(jù)流圖，據(jù)此來(lái)進(jìn)行模塊的函數(shù)劃分與組織；