Visual Basic Coding Conventions
These guidelines are used by Microsoft to develop samples and documentation. The Visual Basic Language Specification does not define a coding standard.
Coding conventions create a consistent look to the code, so that readers can focus on content, not layout.
Conventions let the readers understand the code more quickly, because it allows them to make assumptions based on previous experience.
Conventions make copying, changing, and maintaining the code easier.
Conventions demonstrate Visual Basic "best practices."
Discussion
Naming Conventions
Naming guidelines are covered in Design Guidelines for Developing Class Libraries.
You do not have to change the name of objects created by the Visual Studio designer tools to make them fit the guidelines.
Use namespace qualifications rather than adding Imports statements. If a namespace is imported by default in a project, you do not have to fully qualify the code because it will run unqualified with IntelliSense when copied and pasted. When you are breaking long lines of code to make them easier to read, qualified names can be broken after the "." For example:
Dim collection As System.Diagnostics. InstanceDataCollectionCollectionDo not use "My" or "my" as part of a variable name. This creates confusion with the My objects.
Layout Conventions
Good layout uses formatting to emphasize the structure of the code and makes code easier to read.
Use the pretty listing feature to format code with the default settings (smart indenting, 4 character indents, save tabs as spaces). For more information, see VB Specific, Basic, Text Editor, Options Dialog Box.
Use only one statement per line. Do not use the Visual Basic line continuation character (:).
Use only one declaration per line.
If pretty listing does not format continuation lines, indent continuation lines one tab stop.
Add at least one blank line between method and property definitions.
Commenting Conventions
Do not use comments at the end of a line of code. Put comments on a separate line.
Begin the comment text with an uppercase letter.
End the comment with a period.
Insert one space between the comment delimiter (') and the comment text.
' Here is a comment.Do not create formatted blocks of asterisks that surround comments.
Program Structure
When using the Main method, use the default construct for new console applications, and use My for command-line arguments.
Sub Main() For Each argument As String In My.Application.CommandLineArgs ' Add code here to use the string variable. Next End Sub
Language Guidelines
String Data Type
Use & to concatenate strings:
MsgBox("hello" & vbCrLf & "goodbye")For appending strings in loops, use the StringBuilder object:
Dim longString As New System.Text.StringBuilder For count As Integer = 1 To 1000 longString.Append(count) Next
Type Inference
Take advantage of type inference for local variables:
Public Sub GetQuery()
Dim filterValue = "London"
Dim query = From customer In customers
Where customer.Country = filterValue
End Sub
Relaxed Delegates in Event Handlers
Use relaxed delegates and leave out event arguments if you are not using the event arguments in your code:
Public Sub Form1_Load() Handles Form1.Load
End Sub
Unsigned Data Type
- Use Integer rather than unsigned types unless memory is at a premium.
Arrays
Use the short syntax when initializing arrays on the declaration line:
Dim letters1() As String = {"a", "b", "c"}Rather than this:
Dim letters2() As String = New String() {"a", "b", "c"}Put the array designator on the variable, not on the type:
Dim letters3() As String = {"a", "b", "c"}Rather than this:
Dim letters4 As String() = {"a", "b", "c"}Use the { } syntax when declaring and initializing arrays of basic data types:
Dim letters5() As String = {"a", "b", "c"}Rather than this:
Dim letters6(2) As String letters6(0) = "a" letters6(1) = "b" letters6(2) = "c"
Use the With Keyword
When using a series of calls to one object, consider using the With keyword:
With orderLog
.Log = "Application"
.Source = "Application Name"
.MachineName = "Computer Name"
End With
Use Type Inference for Loop Variables in For or For Each Statements
Allow type inference to determine the type of the loop range variable.
Following is an example of using type inference in a For statement:
For count = 0 To 2
MsgBox(names(count))
Next
Following is an example of using type inference in a For Each statement:
For Each name In names
MsgBox(name)
Next
Use the Try...Catch and Using Statements for Exception Handling
Do not use On Error Goto.
To handle exceptions, use a Try...Catch statement:
Dim conn As New SqlConnection("connection string") Try Conn.Open() Catch ex As SqlException Finally Conn.Close() End TryThe Using statement combines a Try...Catch statement with a call to the Dispose method and simplifies the code. If you are using a Try...Catch statement and the only code in the Finally block is a call to the Dispose method, use the Using statement instead:
Using redPen As New Pen(color.Red) ' Insert code here. End Using
Use the IsNot Keyword
Use the IsNot keyword in preference to Not...Is Nothing.
Use the AndAlso and OrElse Keywords
To avoid exceptions and increase performance by skipping unnecessary code, use AndAlso instead of And and OrElse instead of Or when you perform comparisons:
' Avoid a null reference exception. If the left side of the AndAlso
' operator is False, the right side is not evaluated and a null
' exception is not thrown.
If nullableObject IsNot Nothing AndAlso nullableObject = testValue Then
End If
' Avoid an unnecessary resource-intensive operation. If the left side
' of the OrElse operator is True, the right side is not evaluated and
' a resource-intensive operation is not called.
If testCondition OrElse ResourceIntensiveOperation() Then
End If
Default Instances of Forms
Use Form1.ShowDialog rather than My.Forms.Form1.ShowDialog.
New Keyword
Use short instantiation:
Dim employees As New List(Of String)The preceding line is equivalent to this:
Dim employees2 As List(Of String) = New List(Of String)Use object initializers for new objects instead of the parameterless constructor:
Dim orderLog As New EventLog With { .Log = "Application", .Source = "Application Name", .MachineName = "Computer Name"}
Event Handling
Use Handles rather than AddHandler:
Private Sub ToolStripMenuItem1_Click() Handles ToolStripMenuItem1.Click End SubUse AddressOf, and do not instantiate the delegate explicitly:
Dim closeItem As New ToolStripMenuItem( "Close", Nothing, AddressOf ToolStripMenuItem1_Click) Me.MainMenuStrip.Items.Add(closeItem)When you define an event, use the short syntax and let the compiler define the delegate:
Public Event WhatHappened(ByVal source As Object, ByVal e As WhatHappenedEventArgs)Do not check to see whether an event is Nothing (null) before calling the RaiseEvent method. RaiseEvent checks for Nothing before it raises the event.
Using Shared Members
Call Shared members by using the class name, not from an instance variable.
Use the MsgBox Function
Use MsgBox instead of MessageBox.Show or Console.WriteLine. In environments that do not support the MsgBox function, such as Silverlight, use an appropriate alternative.
Use the My Namespace
Use My features in preference to the .NET Framework class library or the Visual Basic run-time library. For more information, see Objects (Visual Basic).
Use XML Literals
XML literals simplify the most common tasks that you encounter when you work with XML (for example, load, query, and transform). When you develop with XML, follow these guidelines:
Use XML literals to create XML documents and fragments instead of calling XML APIs directly.
Import XML namespaces at the file or project level to take advantage of the performance optimizations for XML literals.
Use the XML axis properties to access elements and attributes in an XML document.
Use embedded expressions to include values and to create XML from existing values instead of using API calls such as the Add method:
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 Queries
Use meaningful names for query variables:
Dim seattleCustomers = From cust In customers Where cust.City = "Seattle"Alias elements in a query to make sure that property names of anonymous types are correctly capitalized using Pascal casing:
Dim customerOrders = From customer In customers Join order In orders On customer.CustomerID Equals order.CustomerID Select Customer = customer, Order = orderRename properties when the property names in the result would be ambiguous. For example, if your query returns a customer name and an order ID, instead of leaving them as Name and ID in the result, rename them:
Dim customerOrders2 = From cust In customers Join ord In orders On cust.CustomerID Equals ord.CustomerID Select CustomerName = cust.Name, OrderID = ord.IDUse type inference in the declaration of query variables and range variables:
Dim customerList = From cust In customersAlign query clauses under the From statement:
Dim newyorkCustomers = From cust In customers Where cust.City = "New York" Select cust.LastName, cust.CompanyNameUse Where clauses before other query clauses to make sure that later query clauses operate on the reduced, filtered set of data:
Dim newyorkCustomers2 = From cust In customers Where cust.City = "New York" Order By cust.LastNameUse the Join clause to explicitly define a join instead of using the Where clause to implicitly define a join:
Dim customerList2 = From cust In customers Join order In orders On cust.CustomerID Equals order.CustomerID Select cust, order
Use the Visual Basic Run-Time Library Members
Use the Visual Basic run-time library in preference to the .NET Framework class library.