轉載請註明出處:http://blog.csdn.net/horkychen
(節選自MSDN-Coding Techniques and Programming Practices)
命名 (Names)
命名最有利於瞭解程式的邏輯結構。一個名字說明是"什麼(what)”比說明"如何(how)"更重要。通過命名可以避免暴露底層的實現，從而保留一個抽象層，簡化了程式的複雜性。例如，你可以使用GetNextStudent()代替GetNextArrayElement()。
一個命名的宗旨是，命名應當基於它的目的進行推敲。名稱必須簡潔且意義明確。對編程(programmatically)而言，命名就是為了易於區分彼此。表達準確的名稱便於閱讀，也便於看代碼的人理解。不過具體的命名方式仍受限於所用的語言和遵循的標準。
以下是推薦的命名技巧:
常式(Routines, 過程或函數)
- 避免可能被誤解的名稱，多為主觀性的名詞，如 Analyze()函數，或變數 xxK8。這樣的名字存在歧義。
- 在物件導向的語言，類的屬性名稱中不需要包含類的名稱。如 Book.BookTitle。可以使用 Book.Title代替。
- 使用動詞 - 名詞(動賓)的結構為方法命名, 如 CalculateInvoiceTotal()。
- 在允許函數重載的語言中，所有重載應該執行類似的功能。對於那些不允許函數重載的語言中，為相似功能的函數建立一個命名標準。
變數(Variables)
- 如果需要，在變數名後追加計算限定符（Avg，Sum，Min，Max，Index）。
- 在變數名中成對使用反義詞，如min/max, begin/end, and open/close，以及get/set等等。
- 由幾個單詞串連的變數名稱，使用大小寫混合的格式，以簡化它們。此外，為了協助區分變數和常式(函數,routine)，常式名稱使用Pascal命名法，所有單詞的首字母都為大寫(CalculateInvoiceTotal)。變數名則使用駝峰命名法(Camel casing)(如documentFormatType)，除第一個單詞首字母小寫外其餘每個單詞除首字母全部大寫。
- 布爾變數名稱應當有是/否或真/假的意味，如 fileIsFound.
- 在命名狀態變數時，避免使用Flag。相對於布爾值，它們可能有兩個以上的值。相對於documentFlag，可以使用一個更具描述性的名稱，如documentFormatType。
- 即使只在幾行代碼中出現的一個臨時變數，也盡量使用有意義的名稱。只把i,j這樣的單字母變數用作小的迴圈變數。
- 如果使用匈牙利命名法，定義一個明確的標準首碼列表，以方便項目中的開發人員使用。欲瞭解更多資訊，請參閱“匈牙利標記法”
- 可以為變數名增加一個符號來標識範圍，如首碼g_的全域變數和m_的模組/類成員變數。
- 常量應該全部大寫，且在單詞間用底線隔開。如NUM_DAYS_IN_WEEK。對於枚舉變數，應當有一個共同的首碼。如FONT_ARIAL或FONT_ROMAN。
資料表(Tables)
- 命名表(tables)時，以單數形式命名。例如，應當使用Employee，而不是Employees。
- 表中的列命名時，不要重複的表的名稱，例如，避免在名為Employee的表中定義欄位EmployeeLastName。
- 不要在列的命名中包含資料類型。日後變更資料類型時，這樣就可以簡化工作。
其它(Miscellaneous)
- 少使用縮寫。如果使用了，就必須要保持一致。縮寫應該只有一個意思，同樣，相應的詞彙也應該只有一個縮寫。例如，如果使用min代表最小化，那就不要讓它表示分鐘(minute)的縮寫。
- 當命名函數時，可以包含對傳回值的描述。如GetCurrentWindowName()。
- 檔案和檔案夾的名稱，就像程式名稱一樣，應準確描述他們所服務的目的是什麼。
- 避免不同類型的元素使用相似的名稱，如稱為ProcessSales()函數和變數iProcessSales。
- 避免同音字命名以方便Code review，如write和right。
- 元素命名時，應避免使用常常拼字錯誤的單詞。當然也要瞭解美式英語和英式英語中一些單詞的差異，如color/colour (都是顏色) and check/cheque(都是支票)。
- 避免使用列印符號標識資料類型。如使用$代表字串或者%代表整數。
注釋(Comments)
軟體文檔存在兩種形式：外部和內部。外部文檔在原始碼之外，如規範，協助檔案和設計檔案。內部文檔則在原始碼中，是由開發人員在開發時寫的注釋組成。
最大的挑戰就是如何確保注釋能與原始碼同步更新。儘管正確注釋原始碼不會左右程式運行，但對於維護特別複雜或繁瑣的軟體，它卻是無價的。
以下是推薦的注釋技巧：
- 修改代碼時，同步更新注釋。
- 在每個方法或函數的開始，提供標準的注釋模板(如Doxygen注釋)，以指樣本程的目的，假設和限制。注釋模板應該是一個簡單的介紹，瞭解方法或函數的目的和功能。
- 避免程式碼的末尾添加註釋，它會使代碼更難閱讀。不過，可以在變數聲明後添加註釋。在這種情況下，可以使用定位字元對齊所有行注釋。
- 避免自訂的注釋集合(clutter comments)方法，如整行的星號。可以使用空格區隔代碼和注釋。
- 避免在註解區塊周圍包上列印符號(typographical frame, $,#,%之類的)。可能你覺得會比較好看，但卻很難維護。
- 在正式發布之前，移除所有臨時或無關的注釋，以避免影響日後的維護工作。
- 如果你需要注釋一段複雜的代碼，應當先檢查，看看能不能重寫(重構)。盡量不要注釋糟糕的代碼，而應當重構它。必須在效能和可維護性之間尋求平衡。
- 注釋要使用完整的句子，它的目的是澄清代碼，而不是再生歧義。
- 及時注釋你的代碼，因為以後更沒時間去做。此外，趁熱打鐵的過一遍代碼會比6周會再做更為有效。
- 不要有多餘的注釋，如幽默的旁白或對公司的控訴。
- 使用注釋來解釋代碼的意圖，而不是代碼的翻譯。
- 注釋任何代碼中比較隱晦的部分。
- 為了防止問題重複出現，給bug修複和解決方案的代碼加上注釋。 這對於團隊尤為重要。
- 為包含迴圈和邏輯分支的代碼添加註釋。這些是有助於讀者閱讀代碼的關鍵位置。
- 使用空格分隔注釋，可以有突出的作用，更易於定位。(Separate comments from comment delimiters with white space. Doing so will make comments stand out and easier to locate when viewed without color clues.)
- 在整個程式中，使用統一的風格，用一致的標點和結構來添加註釋。
