[開發(fā)規(guī)范]編碼排版、注釋規(guī)范

1、軟件開發(fā)規(guī)范試行版Version 1.0編程語言開發(fā)規(guī)范2004-6-31 排版 1-1：程序塊要采用縮進(jìn)風(fēng)格編寫，縮進(jìn)的空格數(shù)為4個(gè)。要求：使用編輯器提供的tab設(shè)置功能，設(shè)置為4；絕對(duì)不允許使用4個(gè)空格字符 1-2：不允許把多個(gè)短語句寫在一行中，即一行只寫一條語句。示例：如下例子不符合規(guī)范。rect.length = 0; rect.width = 0;應(yīng)如下書寫rect.length = 0;rect.width = 0; 1-3：較長的語句（頁寬80字符）要分成多行書寫，長表達(dá)式要在低優(yōu)先級(jí)操作符處劃分新行，操作符放在新行之首，劃分出的新行要進(jìn)行適當(dāng)?shù)目s進(jìn)，使排版整齊，語句可讀。示例：

2、perm_count_msg.head.len = NO7_TO_STAT_PERM_COUNT_LEN + STAT_SIZE_PER_FRAM * sizeof( _UL );act_task_tableframe_id * STAT_TASK_CHECK_NUMBER + index.occupied = stat_poiindex.occupied;act_task_tabletaskno.duration_true_or_false = SYS_get_sccp_statistic_state( stat_item );report_or_not_flag = (taskno MAX

3、_ACT_TASK_NUMBER) & (n7stat_stat_item_valid (stat_item) & (act_task_tabletaskno.result_data != 0); 1-4：if、for、do、while、case、switch、default等語句自占一行，且if、for、do、while等語句的執(zhí)行語句部分無論多少都要加括號(hào)。 示例：如下例子不符合規(guī)范。if (pUserCR = null) return;應(yīng)如下書寫：if (pUserCR = null) return; 1-5：函數(shù)或過程的開始、結(jié)構(gòu)的定義及循環(huán)、判斷等語句中的代碼都要采用縮進(jìn)風(fēng)格，cas

4、e語句下的情況處理語句也要遵從語句縮進(jìn)要求。 1-6：程序塊的分界符（如大括號(hào)和）應(yīng)各獨(dú)占一行并且位于同一列，同時(shí)與引用它們的語句左對(duì)齊。在函數(shù)體的開始、類的定義、結(jié)構(gòu)的定義以及if、for、do、while、switch、case語句中的程序都要采用如上的縮進(jìn)方式。示例：如下例子不符合規(guī)范。if (.) . / program code void example_fun( void ) . / program code 應(yīng)如下書寫。for (.) . / program codeif (.) . / program codevoid example_fun( void ) . / progr

5、am code僅供內(nèi)部使用92 注釋 2-1：一般情況下，源程序有效注釋量必須在20以上。說明：注釋的原則是有助于對(duì)程序的閱讀理解，在該加的地方都加了，注釋不宜太多也不能太少，注釋語言必須準(zhǔn)確、易懂、簡潔。 2-2：文件頭部應(yīng)進(jìn)行注釋，注釋必須列出：版權(quán)說明、版本號(hào)、生成日期、作者、內(nèi)容、功能、修改日志等. 示例：建議所有文件使用該格式；java文件使用javadoc要求的格式/* Copyright (C), 1988-1999, YOEE Info Tech. Co., Ltd. File name: / 文件名 Author: Version: Date: / 作者、版本及完成日期 De

6、scription:/ 用于詳細(xì)說明此程序文件完成的主要功能，與其他模塊 / 或函數(shù)的接口，輸出值、取值范圍、含義及參數(shù)間的控 / 制、順序、獨(dú)立或依賴等關(guān)系Others: / 其它內(nèi)容的說明 History: / 修改歷史記錄列表，每條修改記錄應(yīng)包括修改日期、修改 / 者及修改內(nèi)容簡述 # Date Author Modification1 2*/ 2-3：函數(shù)頭部應(yīng)進(jìn)行注釋，列出：函數(shù)的目的/功能、輸入?yún)?shù)、輸出參數(shù)、返回值、調(diào)用關(guān)系（函數(shù)、表）等。示例：建議所有文件使用該格式；java文件使用javadoc要求的格式/* Description: / 函數(shù)功能、性能等的描述 Pre-Co

7、nditions：/ 前置條件 Param: / 輸入?yún)?shù)說明，包括每個(gè)參數(shù)的作用、取值說明及參數(shù)間關(guān)系。 Return: / 函數(shù)返回值的說明 Others: / 其它說明*/ 2-4：邊寫代碼邊注釋，修改代碼同時(shí)修改相應(yīng)的注釋，以保證注釋與代碼的一致性。不再有用的注釋要?jiǎng)h除。要求：每8行內(nèi)，必須要有一條注釋 2-5：注釋的內(nèi)容要清楚、明了，含義準(zhǔn)確，防止注釋二義性。說明：錯(cuò)誤的注釋不但無益反而有害。2-6：避免在注釋中使用縮寫，特別是非常用縮寫。說明：在使用縮寫時(shí)或之前，應(yīng)對(duì)縮寫進(jìn)行必要的說明。 2-7：注釋應(yīng)與其描述的代碼相近，對(duì)代碼的注釋應(yīng)放在其上方或右方（對(duì)單條語句的注釋）相鄰位置，

8、不可放在下面，如放于上方則需與其上面的代碼用空行隔開。示例：如下例子不符合規(guī)范。例1：/* get replicate sub system index and net indicator */repssn_ind = ssn_dataindex.repssn_index;repssn_ni = ssn_dataindex.ni;例2：repssn_ind = ssn_dataindex.repssn_index;repssn_ni = ssn_dataindex.ni;/* get replicate sub system index and net indicator */應(yīng)如下書寫/ g

9、et replicate sub system index and net indicatorrepssn_ind = ssn_dataindex.repssn_index;repssn_ni = ssn_dataindex.ni; 2-8：注釋與所描述內(nèi)容進(jìn)行同樣的縮排。說明：可使程序排版整齊，并方便注釋的閱讀與理解。示例：如下例子，排版不整齊，閱讀稍感不方便。void example_fun( void )/* code one comments */ CodeBlock One /* code two comments */ CodeBlock Two應(yīng)改為如下布局。void examp

10、le_fun( void ) /* code one comments */ CodeBlock One /* code two comments */ CodeBlock Two 2-9：將注釋與其上面的代碼用空行隔開。示例：如下例子，顯得代碼過于緊湊。/* code one comments */program code one/* code two comments */program code two應(yīng)如下書寫/* code one comments */program code one/* code two comments */program code two 2-10：對(duì)變量的定

11、義和分支語句（條件分支、循環(huán)語句等）必須編寫注釋。說明：這些語句往往是程序?qū)崿F(xiàn)某一特定功能的關(guān)鍵，對(duì)于維護(hù)人員來說，良好的注釋幫助更好的理解程序，有時(shí)甚至優(yōu)于看設(shè)計(jì)文檔。示例：if() /注釋else /注釋2-11：避免在一行代碼或表達(dá)式的中間插入注釋。說明：除非必要，不應(yīng)在代碼或表達(dá)中間插入注釋，否則容易使代碼可理解性變差。2-12：在程序塊的結(jié)束行右方加注釋標(biāo)記，以表明某程序塊的結(jié)束。說明：當(dāng)代碼段較長，特別是多重嵌套時(shí)，這樣做可以使代碼更清晰，更便于閱讀。示例：參見如下例子。if (.) / program code while (index MAX_INDEX) / program

12、code /* end of while (index MAX_INDEX) */ 指明該條while語句結(jié)束 /* end of if (.)*/ / 指明是哪條if語句結(jié)束3 命名 3-1：JAVA命名規(guī)范- Package 的命名 Package 的名字應(yīng)該都是由一個(gè)小寫單詞組成。 - Class 的命名 Class 的名字必須由大寫字母開頭而其他字母都小寫的單詞組成 - 接口的命名 與類名命名方式一致，但在該類名的前面增減大寫字母“I”，表示接口的意思。 - 方法的命名 方法名是一個(gè)動(dòng)詞，采用大小寫混合的方式，第一個(gè)單詞的首字母小寫，其后單詞的首字母大寫。如：run(); runFas

13、t(); getBackground()- Class 變量的命名 變量的名字必須用一個(gè)小寫字母開頭。后面的單詞用大寫字母開頭。變量名不應(yīng)以下劃線或美元符號(hào)開頭(盡管這在語法上是允許的)。變量名應(yīng)簡短且富于描述。變量名的選用應(yīng)該易于記憶，即，能夠指出其用途。盡量避免單個(gè)字符的變量名，除非是一次性的臨時(shí)變量。臨時(shí)變量通常被取名為i，j，k，m和n，它們一般用于整型；c，d，e，它們一般用于字符型。- Static Final 變量的命名 Static Final 變量的名字應(yīng)該都大寫，并且指出完整含義。 - 參數(shù)的命名 參數(shù)的名字必須和變量的命名規(guī)范一致。 - 數(shù)組的命名 數(shù)組應(yīng)該總是用下面的方

14、式來命名： byte buffer;而不是： byte buffer;- 方法的參數(shù) 使用有意義的參數(shù)命名，如果可能的話，使用和要賦值的字段一樣的名字： SetCounter(int size)this.size = size; 3-2：頁文件、文件夾命名及管理命名原則：用代表其含義的英文單詞、以及數(shù)字表示，不易翻譯的用關(guān)鍵字拼音，字母要統(tǒng)一用小寫，不得含空格和特殊字符（下劃線和破折號(hào)除外），最好不要超過8個(gè)字符。管理原則：系統(tǒng)相關(guān)及目錄、文件實(shí)行統(tǒng)一管理。個(gè)人不能隨意創(chuàng)建和修改目錄。原則上，相近的內(nèi)容放在同一目錄下。1. 文件夾命名l 根據(jù)功能或文件類型定義文件夾，例如：css、script、images、public_prompt_infol 根據(jù)網(wǎng)站頻道定義文件夾，例如：首頁（homepage）、我的行程（myjourney） 2. 文件命名l 網(wǎng)頁命名文件名用代表其含義的英文單詞、以及數(shù)字表示，不易翻譯的用關(guān)鍵字拼音。首頁以 default 命名，保存根目錄下。l 被引用文件的命名 （本身不是一個(gè)完整的網(wǎng)頁，可被其它頁面引用）被引入文件統(tǒng)一放在統(tǒng)一文件夾下（如：include ），命名規(guī)則為：如果被引用文件被多個(gè)頻道引用則public_功能.ext例如：“菜單”public_