軟件工程研討源程序文檔化,第六組組員：12122208陳帥12123298馬敏12123249雷晴12123256邱可藝,2014.12.16,1,變量、常量和函數(shù)的命名規(guī)范,2,變量名所有字母小寫，單詞之間用下劃線(_)分開，類成員變量以下劃線結(jié)束。普通變量命名(CommonVariableNames)比如：,類數(shù)據(jù)組成變量命名(ClassDataMembers)數(shù)據(jù)成員（又叫實例變量或者成員變量）的命名與普通變量一樣，全部字母小寫，可選的下劃線分隔符，但應(yīng)該以下劃線結(jié)束。,stringtable_name_;/可以以下劃線結(jié)束stringtablename_;/可以,變量命名(VariableNames),stringtable_name;/可以使用下劃線stringtablename;/可以全部字母小寫stringtableName;/糟糕大小寫混合,3,結(jié)構(gòu)體成員變量命名(StructVariables)結(jié)構(gòu)體成員變量和普通變量命名規(guī)則一致，且不像類成員變量以下劃線結(jié)束。,structUrlTablePropertiesstringname;intnum_entries;,全局變量命名(GlobalVariables)全局變量的使用較為罕見，但當用到時，考慮以前綴g_開頭或標以其他記號，以便與局部變量區(qū)分。,4,常量命名(ConstantNames),K后跟混合大小寫的名稱：kDaysInAWeek。所有編譯時常量，不管是被聲明為局部、全局還是作為類的成員，都應(yīng)該遵守與其他變量命名有輕微差別的命名約定：k后跟單詞首字母大寫的名稱：,constintkDaysInAWeek=7;,5,函數(shù)命名(FunctionNames),正規(guī)函數(shù)名應(yīng)該以大寫字母開頭，單詞首字母大寫，不使用下劃線。如果函數(shù)可能因錯誤而崩潰，應(yīng)該在函數(shù)名后加上OrDie。這僅適用于那些被產(chǎn)品代碼調(diào)用或者正常操作有可能引起錯誤的函數(shù)。,AddTableEntry()DeleteUrl()OpenFileOrDie(),6,訪問器和修改器(AccessorsandMutators)訪問器和修改器（get和set函數(shù)）應(yīng)該與它們關(guān)聯(lián)的變量名匹配。下面顯示了一個類的部分摘錄，它有一個實例變量num_entries,classMyClasspublic:.intnum_entries()constreturnnum_entries;voidset_num_entries(intnum_entries)num_entries=num_entries;private:intnum_entries_;,你也可以使用小寫字母和下劃線來命名非常短小的內(nèi)聯(lián)函數(shù)。比如，如果一個函數(shù)的調(diào)用開銷很小，在循環(huán)調(diào)用時，沒必要緩存其值，這時，小寫字母命名是允許的。,7,對文件、類、函數(shù)、變量和邏輯功能段進行注釋的規(guī)范,8,文件注釋(FileComments),每個文件都應(yīng)該提供版權(quán)信息，然后是文件內(nèi)容的綜合性描述。合法公告和作者信息行(LegalNoticeandAuthorLine)每個文件都應(yīng)依次包括以下條目，1、版權(quán)聲明(比如Copyright2008GoogleInc.)；2、一個許可引用。選擇適合你項目使用的許可引用（比如Apache2.0、BSD、LGPL、GPL）3、作者信息行說明文件原始作者,如果你對原始作者的文件做了實質(zhì)性修改，可以在作者信息行加上你的名字。當其他開發(fā)者有問題時，這樣可以方便他們正確地聯(lián)系到修改者。,9,文件內(nèi)容注釋(FileContents)每個文件都應(yīng)該在其版權(quán)信息及作者信息后面和內(nèi)容前面有一個內(nèi)容描述性的注釋。通常，頭文件描述它所聲明的類的目的及用法。而源文件則應(yīng)該包含更多有關(guān)實現(xiàn)和技巧性算法的討論信息。但如果你覺得這些信息對于頭文件的閱讀者更有用，可以將其放在頭文件中，但在源文件中應(yīng)該注明其文檔在頭文件中。不要在頭文件和源文件中重復(fù)注釋，這樣容易造成歧義。,10,類注釋(ClassComments),每個類定義都應(yīng)該伴隨有說明其目的和用法的注釋。,/遍歷GargantuanTable的內(nèi)容。用法示例：/GargantuanTableIterator*iter=table-NewIterator();/for(iter-seek(“foo”);!iter-done();iter-next()/process(iter-key(),iter-value();/deleteiter;ClassGargantuanTableIterator.,如果你在文件開始就已對類進行了詳細描述，可以在類實現(xiàn)部分簡單地聲明“參見文件開始注釋部分的完整描述”，但注意，這里還是要添加少量注釋。,11,函數(shù)注釋(FunctionComments),函數(shù)聲明部分的注釋描述函數(shù)的用法，實現(xiàn)部分的注釋描述函數(shù)實現(xiàn)的操作。,每個函數(shù)聲明的前面都應(yīng)該有一個描述函數(shù)功能和用法的注釋。這些注釋應(yīng)該是描述性(Opensthefile)，而不是祈使性的（Openthefile），注釋僅僅描述函數(shù)能夠完成什么功能而不是函數(shù)是怎么實現(xiàn)的，這些應(yīng)該在函數(shù)實現(xiàn)的注釋中。在函數(shù)聲明注釋中應(yīng)該提到的信息類型：1、輸入和輸出；2、對于類成員函數(shù)，在該方法的調(diào)用周期外，對象是否有引用參數(shù)，它是否會釋放這些引用；3、如果一個函數(shù)申請了內(nèi)存，它必須釋放它們；4、參數(shù)是否可以是空；5、函數(shù)的使用方法是否會影響其性能；6、如果函數(shù)可重入。它是怎么實現(xiàn)同步的？,12,例子：,/返回這個表的一個迭代器/當遍歷結(jié)束時，由客戶程序負責迭代器的釋放/一旦此迭代器的創(chuàng)建者GargantuanTable對象被釋放/客戶程序不可再使用此迭代器/迭代器被初始化為指向表的開始/這個方法等價于：/Iterator*iter=table-NewIterator();iter-seek(“”);returniter;/如果你想立即尋找返回的迭代器中的另一個位置，使用NewIterator()更快，而/且避免了額外的查找。Iterator*getIterator()const,然而，避免不必要的冗長注釋且不要添加顯而易見的注釋。比如下例外中，返回假的情況就沒必要，因為這很明顯：,/如果表已被占滿，不能再容納實體，則返回真boolIsTableFull();,13,當給構(gòu)造和析構(gòu)函數(shù)加注釋時，注意，讀者清楚地知道這些函數(shù)的作用，所以諸如“銷毀這個對象”的注釋毫無意義。注釋內(nèi)容應(yīng)該說明構(gòu)造函數(shù)怎樣處理參數(shù)（比如它是否取得指針的控制權(quán)）和析構(gòu)函數(shù)怎么完成清理工作。如果這些不很重要，可以省略它們。文件的開頭注釋中沒有關(guān)于析構(gòu)函數(shù)的注釋是很正常的。,函數(shù)定義注釋(FunctionDefinition)每個函數(shù)都應(yīng)該有一個注釋來描述函數(shù)的功能和其完成這些功能的實現(xiàn)技巧（如果有的話）。比如，你在函數(shù)定義注釋中，你可以描述編碼中用到的技巧，給出大致的執(zhí)行步驟或者解釋一下你選擇這種實現(xiàn)而不使用其他替代方法的原因。比如，你可能需要說明為什么函數(shù)前半部分需要鎖而后半部分不需要。注意，不能簡單地重復(fù)頭文件或者其他地方函數(shù)聲明部分的注釋?？梢栽俅胃爬ㄒ幌潞瘮?shù)的功能，但焦點應(yīng)該是函數(shù)是怎么實現(xiàn)功能的。,14,變量注釋(VariableComments),通常，一個變量的實際名稱已經(jīng)提供了足夠和描述信息來說明其用途。但某些情況下，可能需要更多注釋。,類數(shù)據(jù)成員(ClassDataMembers)每個類數(shù)據(jù)成員（也稱實例變量或者成員變量）應(yīng)該有一個描述其用途的注釋。如果這個變量能取得具有特殊意義的標志值，比如NULL或-1，則需要加以說明。比如：,Private:/記錄表中實體的總數(shù)/用于確保不打破數(shù)量限制。/-1意味著表的實體數(shù)未知intnum_total_entries;,15,全局變量(GlobalVariables)和數(shù)據(jù)成員一樣，所有全局變量應(yīng)該有一個描述其功能及其意義的注釋。比如,/所有本次回歸測試使用到的測試用例數(shù)cosntintkNumTestCases=6;,實現(xiàn)注釋(ImplementationComments)在實現(xiàn)中，應(yīng)該對你代碼技巧性的、不明顯的、有趣的或者重要的部分進行注釋。類數(shù)據(jù)成員(ClassDataMembers)技巧性的和復(fù)雜難懂的代碼塊前應(yīng)該有注釋：,/Divideresultbytwo,takingintoaccountthatx/containsthecarryfromtheaddfor(inti=0;isize();i+)x=(x1;X,16,行注釋(LineComments)同樣，當行代碼中有不明顯的地方時，也需要在其行末添加注釋。這種行末注釋應(yīng)該以2個空白與代碼分開。,/Ifwehaveenoughmoney,mmapthedataportiontoo.mmap_budget=max(0,mmap_budgetindex_-length();if(mmap_budget=data_size/Erroralreadylogged.,可以看到，這里即有描述代碼功能的注釋，也有提醒函數(shù)返回時錯誤已經(jīng)被記錄的注釋。如果有多行注釋，將它們整齊排列將增加可讀性。,DoSomething();/CommentheresothecommentslineupDoSomethingElseThatIsLong();/Commentheresotherearetwospaces/betweenthecodeandthecomment/Onespacebeforecommnetwhenopeninganewscopeisallowed,/thusthecommentlinesupwiththefollowingcommentsandcodeDoSomethingElse();/Twospacesbeforelinecommentsnormally,17,邏輯功能段進行注釋,當給函數(shù)傳入NULL、布爾值和整型值串時，應(yīng)該增加注釋以說明這些值的意義，或者你可以使用常量使代碼自文檔化。比較以下兩段代碼：,boolsuccess=CalculateSomething(interesting_value,10,false,NULL);/這些參數(shù)都是什么意思？,VS,boolsuccess=CalculateSomething(interesting_value,10,/默認基數(shù)flase,/非第一次調(diào)用NULL);/無回調(diào),18,也可以使用替代方案，常量或自描述的變量：,constintkDefaultBaseValue=10;constboolkFirstTimeCalling=false;callback*null_callback=NULL;boolsuccess=CalculateSomething(interesting_value,kDefaultBaseValue,kFirstTimeCalling,null_callback);,不要這么做：不要試圖描述代碼本身。假設(shè)代碼閱讀者比你更了解C+，既使這樣，他/她也對你到底想做什么毫無頭緒。,/現(xiàn)在遍歷b數(shù)組并且確保如果i存在，下一個元素是i+1。./天哪，這些都是垃圾注釋,19,函數(shù)聲明和定義、函數(shù)調(diào)用、條件語句、循環(huán)語句和類的格式規(guī)范,20,函數(shù)聲明與定義(FunctionDeclarationsandDefinitions),返回類型和函數(shù)名在同一行，如果空間足夠，參數(shù)列表也應(yīng)在同一行。即：,ReturnTypeClassName:FunctionName(Typepar_name1,Typepar_name2)DoSomething();.,如果一行輸入不完，可以分成多行：,ReturnTypeClassName:ReallyLongFunctionName(Typepar_name1,Typepar_name2,Typepar_name3)DoSomething();.,21,也可以每個參數(shù)各占一行：,ReturnTypeLongClassName:ReallyRealyReallyLongFunctionName(Typepar_name1,/4個空格的縮進Typepar_nane2,Typepar_name3)DoSomething();,22,需要注意的地方：返回類型應(yīng)該保持與函數(shù)名在同一行；左括號應(yīng)該與函數(shù)名保持在同一行且中間不應(yīng)該有空格；括號與參數(shù)之間不應(yīng)該有空格；左花括號應(yīng)該與最后一個參數(shù)保持在同一行；右花括號要么獨自一行，要么與左花括號保持在同一行（其他風格規(guī)則允許時）；右圓括號與左花括號之間應(yīng)該有一個空格隔開；無論是函數(shù)聲明還是函數(shù)實現(xiàn)，都應(yīng)該給參數(shù)命以同樣的名稱；默認縮進2個空格；分行的參數(shù)以4個空格縮進；,23,定義const函數(shù)時，const關(guān)鍵字應(yīng)該與最后一個參數(shù)保持在同一行。,/這個函數(shù)簽名中的所有代碼不超過80個字符ReturnTypeFunctionName(Typepar)const./這個函數(shù)簽名需要分行，但注意，const與最后一個參數(shù)保持在同一行ReturnTypeReallyLongFunctionName(Typepar1,Typepar2)const.,24,如果有未使用參數(shù)，在函數(shù)實現(xiàn)中注釋其名稱：,/在接口中，參數(shù)一定要命名classShapepublic:virtualvoidRotate(doubleradians)=0;/在聲明中，參數(shù)一定要命名classCircle:publicShapevirtualvoidRotate(doubleradians);/在函數(shù)實現(xiàn)中，以注釋注明未使用的參數(shù)命名voidCircle:Rotate(double/*radians*/)/不好如果以后需要其他人實現(xiàn)，參數(shù)名稱不詳voidCircle:Rotate(double),25,函數(shù)調(diào)用(FunctionCalls),盡量書寫在一行，如果字符太多，將參數(shù)分行。比如：,boolretval=DoSomething(argument1,argument2,argumetn3);,如果參數(shù)無法在同一行內(nèi)寫完，可以分行，每一行的參數(shù)都應(yīng)該與第一個參數(shù)對齊，且不要在左圓括號后或右圓括號前加空格。,boolretval=DoSomething(averyveryveryverylongargument1,argument2,argument3);,如果函數(shù)參數(shù)太多，可以每一行寫一個參數(shù)，這樣代碼更可讀：,boolretval=DoSomething(argument1,argument2,argument3,argument4);,26,如果參數(shù)簽名太長，超過最大行寬，可以將參數(shù)分行寫書：,if(.).if(.)DoSomethingTheatRequiresALongFunctionName(very_long_argument1,/縮進4個空格argument2,argument3,argument4);,27,條件語句(Conditonals),括號內(nèi)最好不要有空格，else應(yīng)該另起一行。基本條件語句主要有兩種常見格式：一種是在括號和條件中插入空格，另一種是沒有。但后者更常用。盡管兩種方式都可以，但注意保持一致性。當你修改別人的代碼時，保持與已有風格的一致；而當你添加新代碼時，與當前目錄或項目中已有代碼的風格保持一致。當你不確定而且感覺無所謂時，不要插入空格。,if(condition)/括號內(nèi)沒有空格./縮進2個空格else/else與右花括號在同一行.,28,當然，你也可以根據(jù)自己的喜好在括號內(nèi)插入空格,if(condition)/括號內(nèi)插入空格不常用./縮進2個空格else/else與右花括號在同一行.,注意：if和左圓括號之間應(yīng)該有空格。右圓括號和左花括號（如果使用）之間也應(yīng)該有空格。,if(condition)/糟糕IF后面沒有空格if(condition)/糟糕右圓括號和左花括號之間沒有空格if(condition)/非常糟糕,29,為便于閱讀，簡短的條件語句可以寫在同一行。但僅限于這行代碼很明確且沒有else分支的情況：,if(x=kFoo)returnnewFoo();if(x=kBar)returnnewBar();/if語句有else分支，不允許寫在同一行if(x)DoThis();elseDoThat();,通常，單語句條件語句不需要花括號，但可以根據(jù)自己的喜好加上。有復(fù)雜條件和語句的條件和循環(huán)加上圓括號后更具可讀性。一些項目甚至要求if在所有情況都應(yīng)該加上花括號。,if(condition)DoSomething();/縮進2個空格if(condition)DoSomethign();,30,為保持一致，if或者else分支加了花括號，另一分支也應(yīng)該加上。,/不允許if分支有花括號，而else分支沒有if(condition)foo;elseBar;/不允許else分支有花括號，而if分支沒有If(condition)foo;elsebar;/if和else分支都應(yīng)該加上花括號，因為它們之一有if(condition)foo;elseBar;,31,循環(huán)和多分支語句(LoopsandSwitchStatements),在多分支語句中，塊可以用花括號限制。而對于無循環(huán)體的循環(huán)，可以使用或continue。case語句塊可根據(jù)自己的喜好使用花括號，如果使用花括號，請遵照下面的格式：除非是判斷枚舉類型，多分支語句應(yīng)該有一個默認分支（在枚舉情況下，編譯器將檢測到未處理分支并警告）。如果默認分支不可能被執(zhí)行，使用斷言(assert)聲明。,swtich(var)case0:.