Visual Basic 编码约定

项目
04/07/2023

Microsoft 根据本主题中的准则开发示例和文档。如果你遵循相同的编码约定，可能会获得以下优势：

你的代码将具有一致的外观，使读者能够更好地专注于内容，而不是布局。
读者可以更快地理解你的代码，因为他们可以根据之前的经验做出假设。
你可以更轻松地复制、更改和维护代码。
可帮助确保你的代码展示 Visual Basic 的“最佳做法”。

命名约定

有关命名准则的信息，请参阅命名准则主题。
请勿将“My”或“my”用作变量名称的一部分。这种做法会导致与 My 对象产生混淆。
不需要在自动生成的代码中更改对象的名称来使它们符合准则。

布局约定

插入制表符作为空格，并使用具有四个空格缩进的智能缩进。
使用代码的整齐排列（重格式化）在代码编辑器中重新格式化你的代码。有关详细信息，请参阅选项、文本编辑器、Basic (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。

New 关键字

使用短实例化。例如，请使用以下语法：

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 成员

使用类名来调用 Shared 成员，而不是从实例变量进行调用。

使用 XML 文本

XML 文本可简化在使用 XML 时遇到的最常见的任务（例如加载、查询和转换）。使用 XML 进行开发时，请遵循以下准则：

使用 XML 文本来创建 XML 文档和片段，而不是直接调用 XML API。
在文件或项目级别导入 XML 命名空间以利用 XML 文本的性能优化。
使用 XML 轴属性访问 XML 文档中的元素和属性。

使用嵌入的表达式来包含值并从现有的值创建 XML，而不是使用 Add 方法等 API 调用：

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

如果结果中的属性名称模棱两可，请对属性重命名。例如，如果你的查询返回一个客户名称和一个订单 ID，请对它们进行重命名，而不是在结果中将它们保留为 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

另请参阅

安全编码准则