Visual Basic 編碼慣例

發行項
05/22/2023

Microsoft 會開發遵循本主題指導方針的範例和文件。如果您遵循相同的編碼慣例，可能會獲得下列優點：

您的程式碼會有一致的外觀，讓讀者更能專注於內容，而不是配置。
因為您的程式碼可以根據先前體驗進行假設，所以讀者可以更快速地了解它們。
您可以更輕鬆地複製、變更和維護程式碼。
您可以協助確保程式碼示範 Visual Basic 的「最佳做法」。

命名規範

如需命名指導方針的資訊，請參閱命名指導方針主題。
請勿使用 "My" 或 "my" 作為變數名稱的一部分。這種做法會造成與 My 物件的混淆。
您不需要變更自動產生程式碼中的物件名稱，使其符合指導方針。

版面配置慣例

將索引標籤插入為空格，並使用智慧縮排搭配四個空格縮排。
使用程式碼的美化排列 (重新格式化)，在程式碼編輯器中重新格式化您的程式碼。如需詳細資訊，請參閱選項、文字編輯器、基本 (Visual Basic)。
在每行只使用一個陳述式。請勿使用 Visual Basic 行分隔符號字元 (:)。
請避免使用明確行接續字元 "_"，以在語言允許的位置使用隱含行接續。
在每行只使用一個宣告。
如果程式碼的美化排列 (重新格式化) 不會自動格式化接續行，請手動將接續行縮排一個定位停駐點。不過，請一律將清單中的項目靠左對齊。
```
a As Integer,  
b As Integer  
```
在方法與屬性定義之間新增至少一個空白行。

註解慣例

將註解置於單獨的一行，而非放在程式碼行結尾處。
以大寫字母開始註解文字，並以句號結束註解文字。
在註解分隔符號 (') 與註解文字之間插入一個空格。
```
' Here is a comment.
```
請勿以星號格式化區塊括住註解。

程式結構

當您使用 Main 方法時，請使用新主控台應用程式的預設建構，並針對命令列引數使用 My。

Sub Main()
  For Each argument As String In My.Application.CommandLineArgs
    ' Add code here to use the string variable.
  Next
End Sub

語言指導方針

String 資料類型

使用字串內插補點串連短字串，如下列程式碼所示。
```
MsgBox($"hello{vbCrLf}goodbye")
```

若要在迴圈中附加字串，請使用 StringBuilder 物件。

Dim longString As New System.Text.StringBuilder
For count As Integer = 1 To 1000
  longString.Append(count)
Next

事件處理常式中的寬鬆委派

請勿明確限定事件處理常式的引數 (Object 和 EventArgs)。如果您未使用傳遞至事件的事件引數 (例如 sender As Object、e As EventArgs)、使用寬鬆委派，並省略程式碼中的事件引數：

Public Sub Form1_Load() Handles Form1.Load
End Sub

不帶正負號的資料類型

除非必要，否則請使用 Integer 而非未帶正負號的類型。

陣列

當您在宣告行上初始化陣列時，請使用簡短的語法。例如，使用下列語法。
```
Dim letters1 As String() = {"a", "b", "c"}
```
請勿使用下列語法。
```
Dim letters2() As String = New String() {"a", "b", "c"}
```
將陣列指示項放在類型上，而不是放在變數上。例如，使用下列語法：
```
Dim letters4 As String() = {"a", "b", "c"}
```
請勿使用下列語法：
```
Dim letters3() As String = {"a", "b", "c"}
```
當您宣告和初始化基本資料類型的陣列時，請使用 { } 語法。例如，使用下列語法：
```
Dim letters5 As String() = {"a", "b", "c"}
```
請勿使用下列語法：
```
Dim letters6(2) As String
letters6(0) = "a"
letters6(1) = "b"
letters6(2) = "c"
```

使用 With 關鍵字

當您對一個物件進行一系列呼叫時，請考慮使用 With 關鍵字：

With orderLog
  .Log = "Application"
  .Source = "Application Name"
  .MachineName = "Computer Name"
End With

當您使用例外狀況處理時，請使用 Try...Catch 和 Using 陳述式

請勿使用 On Error Goto。

使用 IsNot 關鍵字

使用 ... IsNot Nothing 取代 Not ... Is Nothing。

新關鍵字

使用簡短具現化。例如，使用下列語法：

Dim employees As New List(Of String)

上述行相當於下列項目：

Dim employees2 As List(Of String) = New List(Of String)

請針對新的物件使用物件初始設定式，而不是無參數建構函式：

Dim orderLog As New EventLog With { 
    .Log = "Application", 
    .Source = "Application Name", 
    .MachineName = "Computer Name"}

事件處理

請使用 Handles，而非 AddHandler：

Private Sub ToolStripMenuItem1_Click() Handles ToolStripMenuItem1.Click
End Sub

請使用 AddressOf，且請勿明確具現化委派：

Dim closeItem As New ToolStripMenuItem( 
    "Close", Nothing, AddressOf ToolStripMenuItem1_Click)
Me.MainMenuStrip.Items.Add(closeItem)

當您定義事件時，請使用簡短語法，並讓編譯器定義委派：

Public Event SampleEvent As EventHandler(Of SampleEventArgs)
' or
Public Event SampleEvent(ByVal source As Object, 
                          ByVal e As SampleEventArgs)

在呼叫 RaiseEvent 方法之前，請勿驗證事件是否為 Nothing (null)。 RaiseEvent 會在引發事件之前檢查 Nothing。

使用共用的成員

使用類別名稱呼叫 Shared 成員，而不是從執行個體變數呼叫成員。

使用 XML 常值

XML 常值可簡化您在使用 XML 時遇到的最常見工作 (例如，載入、查詢和轉換)。當您使用 XML 進行開發時，請遵循下列指導方針：

使用 XML 常值來建立 XML 文件和片段，而不是直接呼叫 XML API。
在檔案或專案層級匯入 XML 命名空間，以利用 XML 常值的效能最佳化。
使用 XML 軸屬性來存取 XML 文件中的元素和屬性。

使用內嵌運算式來包含值，並從現有的值建立 XML，而不是使用 API 呼叫，例如 Add 方法：

Private Function GetHtmlDocument( 
    ByVal items As IEnumerable(Of XElement)) As String

  Dim htmlDoc = <html>
                  <body>
                    <table border="0" cellspacing="2">
                      <%= 
                        From item In items 
                        Select <tr>
                                 <td style="width:480">
                                   <%= item.<title>.Value %>
                                 </td>
                                 <td><%= item.<pubDate>.Value %></td>
                               </tr> 
                      %>
                    </table>
                  </body>
                </html>

  Return htmlDoc.ToString()
End Function

LINQ 查詢

請為查詢變數使用有意義的名稱：

Dim seattleCustomers = From cust In customers 
                       Where cust.City = "Seattle"

在查詢中提供元素名稱，確保匿名型別的屬性名稱正確使用 Pascal 大小寫慣例：

Dim customerOrders = From customer In customers 
                     Join order In orders 
                       On customer.CustomerID Equals order.CustomerID 
                     Select Customer = customer, Order = order

當結果中的屬性名稱可能會造成混淆時，請重新命名屬性。例如，如果您的查詢傳回客戶名稱和訂單識別碼，請將其重新命名，而不是在結果中將它們保留為 Name 和 ID：

Dim customerOrders2 = From cust In customers 
                      Join ord In orders
                        On cust.CustomerID Equals ord.CustomerID 
                      Select CustomerName = cust.Name, 
                             OrderID = ord.ID

在查詢變數和範圍變數的宣告中使用型別推斷：
```
Dim customerList = From cust In customers
```

在 From 陳述式下對齊查詢子句：

Dim newyorkCustomers = From cust In customers 
                       Where cust.City = "New York" 
                       Select cust.LastName, cust.CompanyName

在其他查詢子句之前使用 Where 子句，以便稍後的查詢子句可對經篩選的一組資料進行操作：

Dim newyorkCustomers2 = From cust In customers 
                        Where cust.City = "New York" 
                        Order By cust.LastName

使用 Join 子句來明確定義聯結作業，而不是使用 Where 子句來隱含定義聯結作業：

Dim customerList2 = From cust In customers 
                    Join order In orders 
                      On cust.CustomerID Equals order.CustomerID 
                    Select cust, order

另請參閱

安全程式碼撰寫方針