編碼方法合并了軟件開發的許多方面。盡管它們通常對應用程序的功能沒有影響,但它們對于改善對源代碼的理解是有幫助的。這里考慮了所有形式的源代碼,包括編程、腳本撰寫、標記和查詢語言。 不建議將這里定義的編碼方法形成一套固定的編碼標準。相反,它們旨在作為開發特定軟件項目的編碼標準的指南。 編碼方法分為三部分: 命名 對于理解應用程序的邏輯流,命名方案是最有影響力的一種幫助。名稱應該說明“什么”而不是“如何”。通過避免使用公開基礎實現(它們會發生改變)的名稱,可以保留簡化復雜性的抽象層。例如,可以使用 GetNextStudent(),而不是 GetNextArrayElement()。 命名原則是:選擇正確名稱時的困難可能表明需要進一步分析或定義項的目的。使名稱足夠長以便有一定的意義,并且足夠短以避免冗長。唯一名稱在編程上僅用于將各項區分開。表現力強的名稱是為了幫助人們閱讀;因此,提供人們可以理解的名稱是有意義的。不過,請確保選擇的名稱符合適用語言的規則和標準。 以下幾點是推薦的命名方法。 例程- 避免容易被主觀解釋的難懂的名稱,如對于例程的 AnalyzeThis(),或者對于變量的 xxK8。這樣的名稱會導致多義性,而不僅僅是抽象。
- 在面向對象的語言中,在類屬性的名稱中包含類名是多余的,如 Book.BookTitle。而是應該使用 Book.Title。
- 使用動詞-名詞的方法來命名對給定對象執行特定操作的例程,如 CalculateInvoiceTotal()。
- 在允許函數重載的語言中,所有重載都應該執行相似的函數。對于那些不允許函數重載的語言,建立使相似函數發生關系的命名標準。
變量- 只要合適,在變量名的末尾追加計算限定符(Avg、Sum、Min、Max、Index)。
- 在變量名中使用互補對,如 min/max、begin/end 和 open/close。
- 鑒于大多數名稱都是通過連接若干單詞構造的,請使用大小寫混合的格式以簡化它們的閱讀。另外,為了幫助區分變量和例程,請對例程名稱使用 Pascal 大小寫處理 (CalculateInvoiceTotal),其中每個單詞的第一個字母都是大寫的。對于變量名,請使用 camel 大小寫處理 (documentFormatType),其中除了第一個單詞外每個單詞的第一個字母都是大寫的。
- 布爾變量名應該包含 Is,這意味著 Yes/No 或 True/False 值,如 fileIsFound。
- 在命名狀態變量時,避免使用諸如 Flag 的術語。狀態變量不同于布爾變量的地方是它可以具有兩個以上的可能值。不是使用 documentFlag,而是使用更具描述性的名稱,如 documentFormatType。
- 即使對于可能僅出現在幾個代碼行中的生存期很短的變量,仍然使用有意義的名稱。僅對于短循環索引使用單字母變量名,如 i 或 j。
- 不要使用原義數字或原義字符串,如 For i = 1 To 7。而是使用命名常數,如 For i = 1 To NUM_DAYS_IN_WEEK 以便于維護和理解。
表- 在命名表時,用單數形式表示名稱。例如,使用 Employee,而不是 Employees。
- 在命名表的列時,不要重復表的名稱;例如,在名為 Employee 的表中避免使用名為 EmployeeLastName 的字段。
- 不要在列的名稱中包含數據類型。如果后來有必要更改數據類型,這將減少工作量。
Microsoft SQL Server- 不要給存儲過程加 sp 前綴,這個前綴是為標識系統存儲過程保留的。
- 不要給用戶定義的函數加 fn_ 前綴,這個前綴是為標識內置函數保留的。
- 不要給擴展存儲過程加 xp_ 前綴,這個前綴是為標識系統擴展存儲過程保留的。
雜項- 盡量減少使用縮寫,而是使用以一致方式創建的縮寫。縮寫應該只有一個意思;同樣,每個縮寫詞也應該只有一個縮寫。例如,如果用 min 作為 minimum 的縮寫,那么在所有地方都應這樣做;不要將 min 又用作 minute 的縮寫。
- 在命名函數時包括返回值的說明,如 GetCurrentWindowName()。
- 與過程名一樣,文件和文件夾的名稱也應該精確地說明它們的用途。
- 避免對不同的元素重用名稱,如名為 ProcessSales() 的例程和名為 iProcessSales 的變量。
- 在命名元素時避免同音異義詞(如 write 和 right),以防在檢查代碼時發生混淆。
- 在命名元素時,避免使用普遍拼錯的詞。另外,應清楚區域拼寫之間存在的差異,如 color/colour 和 check/cheque。
- 避免用印刷標記來標識數據類型,如用 $ 代表字符串或用 % 代表整數。
注釋 軟件文檔以兩種形式存在:外部的和內部的。外部文檔(如規范、幫助文件和設計文檔)在源代碼的外部維護。內部文檔由開發人員在開發時在源代碼中編寫的注釋組成。 不考慮外部文檔的可用性,由于硬拷貝文檔可能會放錯地方,源代碼清單應該能夠獨立存在。外部文檔應該由規范、設計文檔、更改請求、錯誤歷史記錄和使用的編碼標準組成。 內部軟件文檔的一個難題是確保注釋的維護與更新與源代碼同時進行。盡管正確注釋源代碼在運行時沒有任何用途,但這對于必須維護特別復雜或麻煩的軟件片段的開發人員來說卻是無價的。 以下幾點是推薦的注釋方法: - 如果用 C# 進行開發,請使用 XML 文檔功能。有關更多信息,請參閱:XML 文檔。
- 修改代碼時,總是使代碼周圍的注釋保持最新。
- 在每個例程的開始,提供標準的注釋樣本以指示例程的用途、假設和限制很有幫助。注釋樣本應該是解釋它為什么存在和可以做什么的簡短介紹。
- 避免在代碼行的末尾添加注釋;行尾注釋使代碼更難閱讀。不過在批注變量聲明時,行尾注釋是合適的;在這種情況下,將所有行尾注釋在公共制表位處對齊。
- 避免雜亂的注釋,如一整行星號。而是應該使用空白將注釋同代碼分開。
- 避免在塊注釋的周圍加上印刷框。這樣看起來可能很漂亮,但是難于維護。
- 在部署之前,移除所有臨時或無關的注釋,以避免在日后的維護工作中產生混亂。
- 如果需要用注釋來解釋復雜的代碼節,請檢查此代碼以確定是否應該重寫它。盡一切可能不注釋難以理解的代碼,而應該重寫它。盡管一般不應該為了使代碼更簡單以便于人們使用而犧牲性能,但必須保持性能和可維護性之間的平衡。
- 在編寫注釋時使用完整的句子。注釋應該闡明代碼,而不應該增加多義性。
- 在編寫代碼時就注釋,因為以后很可能沒有時間這樣做。另外,如果有機會復查已編寫的代碼,在今天看來很明顯的東西六周以后或許就不明顯了。
- 避免多余的或不適當的注釋,如幽默的不主要的備注。
- 使用注釋來解釋代碼的意圖。它們不應作為代碼的聯機翻譯。
- 注釋代碼中不十分明顯的任何內容。
- 為了防止問題反復出現,對錯誤修復和解決方法代碼總是使用注釋,尤其是在團隊環境中。
- 對由循環和邏輯分支組成的代碼使用注釋。這些是幫助源代碼讀者的主要方面。
- 在整個應用程序中,使用具有一致的標點和結構的統一樣式來構造注釋。
- 用空白將注釋同注釋分隔符分開。在沒有顏色提示的情況下查看注釋時,這樣做會使注釋很明顯且容易被找到。
格式 格式化使代碼的邏輯結構很明顯。花時間確保源代碼以一致的邏輯方式進行格式化,這對于您和必須解密源代碼的其他開發人員都有幫助。 以下幾點是推薦的格式化方法。 - 建立標準的縮進大小(如四個空格),并一致地使用此標準。用規定的縮進對齊代碼節。
- 在發布源代碼的硬拷貝版本時使用 monotype 字體。
- 在括號對對齊的位置垂直對齊左括號和右括號,如:
for (i = 0; i < 100; i++){ ...} 還可以使用傾斜樣式,即左括號出現在行尾,右括號出現在行首,如: for (i = 0; i < 100; i++){ ...} 無論選擇哪種樣式,請在整個源代碼中使用那個樣式。 - 沿邏輯結構行縮進代碼。沒有縮進,代碼將變得難以理解,如:
If ... ThenIf ... Then...ElseEnd IfElse...End If 縮進代碼會產生出更容易閱讀的代碼,如: If ... Then If ... Then ... Else ... End IfElse...End If - 為注釋和代碼建立最大的行長度,以避免不得不滾動源代碼編輯器,并且可以提供整齊的硬拷貝表示形式。
- 在大多數運算符之前和之后使用空格,這樣做時不會改變代碼的意圖。但是,C++ 中使用的指針表示法是一個例外。
- 使用空白為源代碼提供結構線索。這樣做會創建代碼“段”,有助于讀者理解軟件的邏輯分段。
- 當一行被分為幾行時,通過將串聯運算符放在每一行的末尾而不是開頭,清楚地表示沒有后面的行是不完整的。
- 只要合適,每一行上放置的語句避免超過一條。例外是 C、C++、C# 或 JScript 中的循環,如 for (i = 0; i < 100; i++)。
- 編寫 HTML 時,建立標準的標記和屬性格式,如所有標記都大寫或所有屬性都小寫。另一種方法是,堅持 XHTML 規范以確保所有 HTML 文檔都有效。盡管在創建 Web 頁時需折中考慮文件大小,但應使用帶引號的屬性值和結束標記以方便維護。
- 編寫 SQL 語句時,對于關鍵字使用全部大寫,對于數據庫元素(如表、列和視圖)使用大小寫混合。
- 在物理文件之間在邏輯上劃分源代碼。
- 將每個主要的 SQL 子句放在不同的行上,這樣更容易閱讀和編輯語句,例如:
SELECT FirstName, LastNameFROM CustomersWHERE State = 'WA' - 將大的復雜代碼節分為較小的、易于理解的模塊。
|