Visual Studio 編碼方法

Visual Studio   編碼方法

    編碼方法合并了軟體開發的許多方面。儘管它們通常對應用程式的功能沒有影響，但它們對於改善對原始碼的理解是有協助的。這裡考慮了所有形式的原始碼，包括編程、指令碼撰寫、標記和查詢語言。

    不建議將這裡定義的編碼方法形成一套固定的編碼通訊協定。相反，它們旨在作為開發特定軟體項目的編碼通訊協定的指南。

    編碼方法分為三部分：

• 命名
• 注釋
• 格式

命名

    對於理解應用程式的邏輯流，命名方案是最有影響力的一種協助。名稱應該說明“什麼”而不是“如何”。通過避免使用公開基礎實現（它們會發生改變）的名稱，可以保留簡化複雜性的抽象層。例如，可以使用 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'

• 將大的複雜代碼節分為較小的、易於理解的模組。