《源程序文檔化【業(yè)界薈萃】》由會(huì)員分享，可在線(xiàn)閱讀，更多相關(guān)《源程序文檔化【業(yè)界薈萃】（36頁(yè)珍藏版）》請(qǐng)?jiān)谘b配圖網(wǎng)上搜索。
1、軟件工程研討源程序文檔化第六組組員：12122208 陳帥12123298 馬敏12123249 雷晴12123256 邱可藝2014.12.161行業(yè)知識(shí)變量、常量和函數(shù)的命名規(guī)范2行業(yè)知識(shí)變量名所有字母小寫(xiě)，單詞之間用下劃線(xiàn)(_)分開(kāi)，類(lèi)成員變量以下劃線(xiàn)結(jié)束。普通變量命名(Common Variable Names)比如：類(lèi)數(shù)據(jù)組成變量命名(Class Data Members)數(shù)據(jù)成員（又叫實(shí)例變量或者成員變量）的命名與普通變量一樣，全部字母小寫(xiě)，可選的下劃線(xiàn)分隔符，但應(yīng)該以下劃線(xiàn)結(jié)束。string table_name_; / 可以以下劃線(xiàn)結(jié)束string tablename_; /
2、可以變量命名變量命名(Variable Names)string table_name; / 可以使用下劃線(xiàn)string tablename; / 可以全部字母小寫(xiě)string tableName; / 糟糕大小寫(xiě)混合3行業(yè)知識(shí)結(jié)構(gòu)體成員變量命名(Struct Variables)結(jié)構(gòu)體成員變量和普通變量命名規(guī)則一致，且不像類(lèi)成員變量以下劃線(xiàn)結(jié)束。struct UrlTableProperties string name; int num_entries;全局變量命名(Global Variables)全局變量的使用較為罕見(jiàn)，但當(dāng)用到時(shí)，考慮以前綴g_開(kāi)頭或標(biāo)以其他記號(hào)，以便與局部變量區(qū)分。4
3、行業(yè)知識(shí)常量命名常量命名(Constant Names)K后跟混合大小寫(xiě)的名稱(chēng)：kDaysInAWeek。所有編譯時(shí)常量，不管是被聲明為局部、全局還是作為類(lèi)的成員，都應(yīng)該遵守與其他變量命名有輕微差別的命名約定：k后跟單詞首字母大寫(xiě)的名稱(chēng)：const int kDaysInAWeek = 7;5行業(yè)知識(shí)函數(shù)命名函數(shù)命名(Function Names)正規(guī)函數(shù)名應(yīng)該以大寫(xiě)字母開(kāi)頭，單詞首字母大寫(xiě)，不使用下劃線(xiàn)。如果函數(shù)可能因錯(cuò)誤而崩潰，應(yīng)該在函數(shù)名后加上OrDie。這僅適用于那些被產(chǎn)品代碼調(diào)用或者正常操作有可能引起錯(cuò)誤的函數(shù)。AddTableEntry()DeleteUrl()OpenFileOr
4、Die()6行業(yè)知識(shí)訪(fǎng)問(wèn)器和修改器(Accessors and Mutators)訪(fǎng)問(wèn)器和修改器（get和set函數(shù)）應(yīng)該與它們關(guān)聯(lián)的變量名匹配。下面顯示了一個(gè)類(lèi)的部分摘錄，它有一個(gè)實(shí)例變量num_entriesclass MyClass public:.int num_entries() constreturn num_entries;v o i d s e t _ n u m _ e n t r i e s ( i n t num_entries)num_entries = num_entries;private: int num_entries_;你也可以使用小寫(xiě)字母和下劃線(xiàn)來(lái)命名非常短
5、小的內(nèi)聯(lián)函數(shù)。比如，如果一個(gè)函數(shù)的調(diào)用開(kāi)銷(xiāo)很小，在循環(huán)調(diào)用時(shí)，沒(méi)必要緩存其值，這時(shí)，小寫(xiě)字母命名是允許的。7行業(yè)知識(shí)對(duì)文件、類(lèi)、函數(shù)、變量和邏輯功能段進(jìn)行注釋的規(guī)范8行業(yè)知識(shí) 文件注釋文件注釋(File Comments)每個(gè)文件都應(yīng)該提供版權(quán)信息，然后是文件內(nèi)容的綜合性描述。合法公告和作者信息行(Legal Notice and Author Line)每個(gè)文件都應(yīng)依次包括以下條目，1、版權(quán)聲明(比如Copyright 2008 Google Inc.)；2、一個(gè)許可引用。選擇適合你項(xiàng)目使用的許可引用（比如Apache 2.0、BSD、LGPL、GPL）3、作者信息行說(shuō)明文件原始作者如果你對(duì)
6、原始作者的文件做了實(shí)質(zhì)性修改，可以在作者信息行加上你的名字。當(dāng)其他開(kāi)發(fā)者有問(wèn)題時(shí)，這樣可以方便他們正確地聯(lián)系到修改者。9行業(yè)知識(shí)文件內(nèi)容注釋(File Contents)每個(gè)文件都應(yīng)該在其版權(quán)信息及作者信息后面和內(nèi)容前面有一個(gè)內(nèi)容描述性的注釋。通常，頭文件描述它所聲明的類(lèi)的目的及用法。而源文件則應(yīng)該包含更多有關(guān)實(shí)現(xiàn)和技巧性算法的討論信息。但如果你覺(jué)得這些信息對(duì)于頭文件的閱讀者更有用，可以將其放在頭文件中，但在源文件中應(yīng)該注明其文檔在頭文件中。不要在頭文件和源文件中重復(fù)注釋?zhuān)@樣容易造成歧義。10行業(yè)知識(shí)類(lèi)注釋類(lèi)注釋(Class Comments)每個(gè)類(lèi)定義都應(yīng)該伴隨有說(shuō)明其目的和用法的注釋。/
7、 遍歷GargantuanTable的內(nèi)容。用法示例：/ GargantuanTableIterator* iter = table-NewIterator();/ for(iter-seek(“foo”);!iter-done();iter-next()/ process(iter-key(),iter-value();/ / delete iter;Class GargantuanTableIterator.如果你在文件開(kāi)始就已對(duì)類(lèi)進(jìn)行了詳細(xì)描述，可以在類(lèi)實(shí)現(xiàn)部分簡(jiǎn)單地聲明“參見(jiàn)文件開(kāi)始注釋部分的完整描述”，但注意，這里還是要添加少量注釋。11行業(yè)知識(shí)函數(shù)注釋函數(shù)注釋(Function C
8、omments)函數(shù)聲明部分的注釋描述函數(shù)的用法，實(shí)現(xiàn)部分的注釋描述函數(shù)實(shí)現(xiàn)的操作。每個(gè)函數(shù)聲明的前面都應(yīng)該有一個(gè)描述函數(shù)功能和用法的注釋。這些注釋?xiě)?yīng)該是描述性(Opens the file)，而不是祈使性的（Open the file），注釋僅僅描述函數(shù)能夠完成什么功能而不是函數(shù)是怎么實(shí)現(xiàn)的，這些應(yīng)該在函數(shù)實(shí)現(xiàn)的注釋中。在函數(shù)聲明注釋中應(yīng)該提到的信息類(lèi)型：1、輸入和輸出；2、對(duì)于類(lèi)成員函數(shù)，在該方法的調(diào)用周期外，對(duì)象是否有引用參數(shù)，它是否會(huì)釋放這些引用；3、如果一個(gè)函數(shù)申請(qǐng)了內(nèi)存，它必須釋放它們；4、參數(shù)是否可以是空；5、函數(shù)的使用方法是否會(huì)影響其性能；6、如果函數(shù)可重入。它是怎么實(shí)現(xiàn)同步的
9、？12行業(yè)知識(shí)例子：/ 返回這個(gè)表的一個(gè)迭代器/ 當(dāng)遍歷結(jié)束時(shí)，由客戶(hù)程序負(fù)責(zé)迭代器的釋放/ 一旦此迭代器的創(chuàng)建者GargantuanTable對(duì)象被釋放/ 客戶(hù)程序不可再使用此迭代器/ 迭代器被初始化為指向表的開(kāi)始/ 這個(gè)方法等價(jià)于：/ Iterator *iter = table-NewIterator();iter-seek(“”);return iter;/ 如果你想立即尋找返回的迭代器中的另一個(gè)位置，使用NewIterator()更快，而/ 且避免了額外的查找。Iterator* getIterator()const然而，避免不必要的冗長(zhǎng)注釋且不要添加顯而易見(jiàn)的注釋。比如下例外中，返
10、回假的情況就沒(méi)必要，因?yàn)檫@很明顯：/ 如果表已被占滿(mǎn)，不能再容納實(shí)體，則返回真bool IsTableFull();13行業(yè)知識(shí)當(dāng)給構(gòu)造和析構(gòu)函數(shù)加注釋時(shí)，注意，讀者清楚地知道這些函數(shù)的作用，所以諸如“銷(xiāo)毀這個(gè)對(duì)象”的注釋毫無(wú)意義。注釋內(nèi)容應(yīng)該說(shuō)明構(gòu)造函數(shù)怎樣處理參數(shù)（比如它是否取得指針的控制權(quán)）和析構(gòu)函數(shù)怎么完成清理工作。如果這些不很重要，可以省略它們。文件的開(kāi)頭注釋中沒(méi)有關(guān)于析構(gòu)函數(shù)的注釋是很正常的。函數(shù)定義注釋(Function Definition)每個(gè)函數(shù)都應(yīng)該有一個(gè)注釋來(lái)描述函數(shù)的功能和其完成這些功能的實(shí)現(xiàn)技巧（如果有的話(huà)）。比如，你在函數(shù)定義注釋中，你可以描述編碼中用到的技巧，給
11、出大致的執(zhí)行步驟或者解釋一下你選擇這種實(shí)現(xiàn)而不使用其他替代方法的原因。比如，你可能需要說(shuō)明為什么函數(shù)前半部分需要鎖而后半部分不需要。注意，不能簡(jiǎn)單地重復(fù)頭文件或者其他地方函數(shù)聲明部分的注釋?？梢栽俅胃爬ㄒ幌潞瘮?shù)的功能，但焦點(diǎn)應(yīng)該是函數(shù)是怎么實(shí)現(xiàn)功能的。14行業(yè)知識(shí)變量注釋變量注釋(Variable Comments)通常，一個(gè)變量的實(shí)際名稱(chēng)已經(jīng)提供了足夠和描述信息來(lái)說(shuō)明其用途。但某些情況下，可能需要更多注釋。類(lèi)數(shù)據(jù)成員(Class Data Members)每個(gè)類(lèi)數(shù)據(jù)成員（也稱(chēng)實(shí)例變量或者成員變量）應(yīng)該有一個(gè)描述其用途的注釋。如果這個(gè)變量能取得具有特殊意義的標(biāo)志值，比如NULL或-1，則需要加
12、以說(shuō)明。比如：Private: /記錄表中實(shí)體的總數(shù) /用于確保不打破數(shù)量限制。 /-1意味著表的實(shí)體數(shù)未知 int num_total_entries;15行業(yè)知識(shí)全局變量(Global Variables)和數(shù)據(jù)成員一樣，所有全局變量應(yīng)該有一個(gè)描述其功能及其意義的注釋。比如/ 所有本次回歸測(cè)試使用到的測(cè)試用例數(shù)cosnt int kNumTestCases = 6;實(shí)現(xiàn)注釋(Implementation Comments)在實(shí)現(xiàn)中，應(yīng)該對(duì)你代碼技巧性的、不明顯的、有趣的或者重要的部分進(jìn)行注釋。類(lèi)數(shù)據(jù)成員(Class Data Members)技巧性的和復(fù)雜難懂的代碼塊前應(yīng)該有注釋?zhuān)? Di
13、vide result by two, taking into account that x / contains the carry from the addfor(int i = 0;i size();i+) x = (x 1; X &= 1;16行業(yè)知識(shí)行注釋(Line Comments)同樣，當(dāng)行代碼中有不明顯的地方時(shí)，也需要在其行末添加注釋。這種行末注釋?xiě)?yīng)該以2個(gè)空白與代碼分開(kāi)。/ If we have enough money, mmap the data portion too.mmap_budget = max(0,mmap_budget index_-length();i f
14、 ( m m a p _ b u d g e t = d a t a _ s i z e & !mmapData(mmap_chunk_bytes,mlock)return; / Error already logged.可以看到，這里即有描述代碼功能的注釋?zhuān)灿刑嵝押瘮?shù)返回時(shí)錯(cuò)誤已經(jīng)被記錄的注釋。如果有多行注釋?zhuān)瑢⑺鼈冋R排列將增加可讀性。DoSomething(); / Comment here so the comments line upDoSomethingElseThatIsLong(); / Comment here so there are two spaces / betwe
15、en the code and the comment/ One space before commnet when opening a new scope is allowed, / thus the comment lines up with the following comments and code DoSomethingElse(); / Two spaces before line comments normally17行業(yè)知識(shí)邏輯功能段進(jìn)行注釋當(dāng)給函數(shù)傳入NULL、布爾值和整型值串時(shí)，應(yīng)該增加注釋以說(shuō)明這些值的意義，或者你可以使用常量使代碼自文檔化。比較以下兩段代碼：bool
16、success = CalculateSomething(interesting_value, 10, false, NULL);/這些參數(shù)都是什么意思？VSbool success = CalculateSomething(interesting_value, 10, /默認(rèn)基數(shù) flase,/非第一次調(diào)用 NULL);/無(wú)回調(diào)18行業(yè)知識(shí)也可以使用替代方案，常量或自描述的變量：const int kDefaultBaseValue = 10;const bool kFirstTimeCalling = false;callback *null_callback = NULL;bool su
17、ccess = CalculateSomething(interesting_value, kDefaultBaseValue, kFirstTimeCalling, null_callback);不要這么做：不要試圖描述代碼本身。假設(shè)代碼閱讀者比你更了解C+，既使這樣，他/她也對(duì)你到底想做什么毫無(wú)頭緒。/ 現(xiàn)在遍歷b數(shù)組并且確保如果i存在，下一個(gè)元素是i+1。./ 天哪，這些都是垃圾注釋19行業(yè)知識(shí)函數(shù)聲明和定義、函數(shù)調(diào)用、條件語(yǔ)句、循環(huán)語(yǔ)句和類(lèi)的格式規(guī)范20行業(yè)知識(shí)函數(shù)聲明與定義(Function Declarations and Definitions)返回類(lèi)型和函數(shù)名在同一行，如果空間
18、足夠，參數(shù)列表也應(yīng)在同一行。即：ReturnType ClassName:FunctionName(Type par_name1,Type par_name2) DoSomething(); .如果一行輸入不完，可以分成多行：ReturnType ClassName:ReallyLongFunctionName(Type par_name1,Type par_name2, Type par_name3) DoSomething(); .21行業(yè)知識(shí)也可以每個(gè)參數(shù)各占一行：ReturnType LongClassName:ReallyRealyReallyLongFunctionName(Typ
19、e par_name1, / 4個(gè)空格的縮進(jìn)Type par_nane2,Type par_name3) DoSomething();22行業(yè)知識(shí)需要注意的地方：返回類(lèi)型應(yīng)該保持與函數(shù)名在同一行；左括號(hào)應(yīng)該與函數(shù)名保持在同一行且中間不應(yīng)該有空格；括號(hào)與參數(shù)之間不應(yīng)該有空格；左花括號(hào)應(yīng)該與最后一個(gè)參數(shù)保持在同一行；右花括號(hào)要么獨(dú)自一行，要么與左花括號(hào)保持在同一行（其他風(fēng)格規(guī)則允許時(shí)）；右圓括號(hào)與左花括號(hào)之間應(yīng)該有一個(gè)空格隔開(kāi)；無(wú)論是函數(shù)聲明還是函數(shù)實(shí)現(xiàn)，都應(yīng)該給參數(shù)命以同樣的名稱(chēng)；默認(rèn)縮進(jìn)2個(gè)空格；分行的參數(shù)以4個(gè)空格縮進(jìn)；23行業(yè)知識(shí)定義const函數(shù)時(shí)，const關(guān)鍵字應(yīng)該與最后一個(gè)參數(shù)保持
20、在同一行。/ 這個(gè)函數(shù)簽名中的所有代碼不超過(guò)80個(gè)字符ReturnType FunctionName(Type par) const ./ 這個(gè)函數(shù)簽名需要分行，但注意，const與最后一個(gè)參數(shù)保持在同一行ReturnType ReallyLongFunctionName(Type par1, Type par2)const .24行業(yè)知識(shí)如果有未使用參數(shù)，在函數(shù)實(shí)現(xiàn)中注釋其名稱(chēng)：/ 在接口中，參數(shù)一定要命名class Shape public:virtual void Rotate(double radians) = 0;/ 在聲明中，參數(shù)一定要命名class Circle : public
21、 Shape virtual void Rotate(double radians);/ 在函數(shù)實(shí)現(xiàn)中，以注釋注明未使用的參數(shù)命名void Circle:Rotate(double /*radians*/)/ 不好如果以后需要其他人實(shí)現(xiàn)，參數(shù)名稱(chēng)不詳void Circle:Rotate(double)25行業(yè)知識(shí)函數(shù)調(diào)用函數(shù)調(diào)用(Function Calls)盡量書(shū)寫(xiě)在一行，如果字符太多，將參數(shù)分行。比如：bool retval = DoSomething(argument1,argument2,argumetn3);如果參數(shù)無(wú)法在同一行內(nèi)寫(xiě)完，可以分行，每一行的參數(shù)都應(yīng)該與第一個(gè)參數(shù)對(duì)齊，且
22、不要在左圓括號(hào)后或右圓括號(hào)前加空格。bool retval = DoSomething(averyveryveryverylongargument1, argument2,argument3);如果函數(shù)參數(shù)太多，可以每一行寫(xiě)一個(gè)參數(shù)，這樣代碼更可讀：bool retval = DoSomething(argument1, argument2, argument3, argument4);26行業(yè)知識(shí)如果參數(shù)簽名太長(zhǎng)，超過(guò)最大行寬，可以將參數(shù)分行寫(xiě)書(shū)：if(.) . . if(.) DoSomethingTheatRequiresALongFunctionName( very_long_argu
23、ment1, / 縮進(jìn)4個(gè)空格 argument2, argument3, argument4);27行業(yè)知識(shí)條件語(yǔ)句條件語(yǔ)句(Conditonals)括號(hào)內(nèi)最好不要有空格，else應(yīng)該另起一行?；緱l件語(yǔ)句主要有兩種常見(jiàn)格式：一種是在括號(hào)和條件中插入空格，另一種是沒(méi)有。但后者更常用。盡管兩種方式都可以，但注意保持一致性。當(dāng)你修改別人的代碼時(shí)，保持與已有風(fēng)格的一致；而當(dāng)你添加新代碼時(shí)，與當(dāng)前目錄或項(xiàng)目中已有代碼的風(fēng)格保持一致。當(dāng)你不確定而且感覺(jué)無(wú)所謂時(shí)，不要插入空格。if(condition) / 括號(hào)內(nèi)沒(méi)有空格 . / 縮進(jìn)2個(gè)空格else / else與右花括號(hào)在同一行 .28行業(yè)知識(shí)當(dāng)然
24、，你也可以根據(jù)自己的喜好在括號(hào)內(nèi)插入空格if ( condition ) / 括號(hào)內(nèi)插入空格不常用 . / 縮進(jìn)2個(gè)空格else / else與右花括號(hào)在同一行 .注意：if和左圓括號(hào)之間應(yīng)該有空格。右圓括號(hào)和左花括號(hào)（如果使用）之間也應(yīng)該有空格。if(condition) / 糟糕IF后面沒(méi)有空格if (condition) / 糟糕右圓括號(hào)和左花括號(hào)之間沒(méi)有空格if(condition) / 非常糟糕29行業(yè)知識(shí)為便于閱讀，簡(jiǎn)短的條件語(yǔ)句可以寫(xiě)在同一行。但僅限于這行代碼很明確且沒(méi)有else分支的情況：if (x = kFoo) return new Foo();if (x = kBar)
25、return new Bar();/ if語(yǔ)句有else分支，不允許寫(xiě)在同一行if (x) DoThis();else DoThat();通常，單語(yǔ)句條件語(yǔ)句不需要花括號(hào)，但可以根據(jù)自己的喜好加上。有復(fù)雜條件和語(yǔ)句的條件和循環(huán)加上圓括號(hào)后更具可讀性。一些項(xiàng)目甚至要求if在所有情況都應(yīng)該加上花括號(hào)。if ( condition ) DoSomething(); / 縮進(jìn)2個(gè)空格if (condition) DoSomethign();30行業(yè)知識(shí)為保持一致，if或者else分支加了花括號(hào)，另一分支也應(yīng)該加上。/ 不允許if分支有花括號(hào)，而else分支沒(méi)有if (condition) foo;el
26、se Bar;/ 不允許else分支有花括號(hào)，而if分支沒(méi)有If (condition) foo;else bar;/ if和else分支都應(yīng)該加上花括號(hào)，因?yàn)樗鼈冎挥衖f (condition) foo;else Bar;31行業(yè)知識(shí)循環(huán)和多分支語(yǔ)句循環(huán)和多分支語(yǔ)句(Loops and Switch Statements)在多分支語(yǔ)句中，塊可以用花括號(hào)限制。而對(duì)于無(wú)循環(huán)體的循環(huán)，可以使用或continue。case語(yǔ)句塊可根據(jù)自己的喜好使用花括號(hào)，如果使用花括號(hào)，請(qǐng)遵照下面的格式：除非是判斷枚舉類(lèi)型，多分支語(yǔ)句應(yīng)該有一個(gè)默認(rèn)分支（在枚舉情況下，編譯器將檢測(cè)到未處理分支并警告）。如果默認(rèn)分支
27、不可能被執(zhí)行，使用斷言(assert)聲明。swtich (var) case 0: .Break;case 1: . Break;default: assert(false);32行業(yè)知識(shí)空循環(huán)體應(yīng)該用或者continue，但不要用單獨(dú)的分號(hào)：while (condition) / 一直測(cè)試條件，直到它返回假for(int i = 0; i kSomeNumber;+i) / 很好空循環(huán)體while (condtiton) continue; / 很好continue指示無(wú)邏輯while (condition); / 糟糕看起來(lái)像是do/while循環(huán)33行業(yè)知識(shí)類(lèi)格式(Class Form
28、at)成員按public、protected和private的次序定義，每個(gè)部分縮進(jìn)1個(gè)空格。下例顯示了基本的類(lèi)格式（例子中缺少必要的注釋?zhuān)瑓⒁?jiàn)類(lèi)注釋(Class Comments)部分）：class MyClass : public OtherClass public: / 注意，縮進(jìn)1個(gè)空格 MyClass(); / 注意，縮進(jìn)2個(gè)空格 Explicit MyClass(int var); MyClass() void SomeFunction(); void SomeFunctionThatDoesNothing()void set_some_var(int var) some_var
29、= var; int some_var() const reurn some_var; private: bool SomeInternalFunction(); int some_var; int some_other_var; DISALLOW_COPY_AND_ASSIGN(MyClass);34行業(yè)知識(shí)注意：基類(lèi)名稱(chēng)直接置于子類(lèi)名稱(chēng)后的同一行內(nèi)而不受最大長(zhǎng)度（80字符）的限制；public:protected:和private:只需縮進(jìn)1個(gè)空格，且除非是第1個(gè)實(shí)例的情況，它們應(yīng)該位于單獨(dú)的行，最好在緊接著的下一行進(jìn)行成員聲明；public部分行1位、protected部分第2位，private放在最后；35行業(yè)知識(shí)謝謝36行業(yè)知識(shí)
源程序文檔化【業(yè)界薈萃】
