Class and Module statements define regions of code that you can expand or collapse to make the code easier to understand. Subroutines and functions also define collapsible code sections. In addition to these, you can use the Region statement to create your own collapsible sections of code. You can place subroutines that have a common purpose in a region so you can collapse and expand the code as needed. The following code shows a simple region:

#Region "Drawing Routines"
     ...
#End Region

Note that the IDE's search-and-replace features normally work only on expanded regions. If you collapse a region and make a global search-and-replace in the current document or the current selection, the collapsed code remains unchanged. If you make a global replace throughout the whole project, the replacement occurs within collapsed regions as well.

By itself, the End Region statement does not tell you which region it is ending. You can make your code easier to understand, particularly if you have many regions in the same module, by adding a comment after the End Region statement giving the name of the region, as shown in the following code:

#Region "Drawing Routines"
    ...
#End Region ' Drawing Routines

Sometimes it may be easier to move related pieces of code into separate files. The Partial keyword allows you to place parts of a class in different files. For example, you could move a form's code for loading and saving data into a separate file and use the Partial keyword to indicate that the code was part of the form. Chapter 26, "Classes and Structures," describes the Partial keyword in detail.

However, you cannot use the Partial keyword with modules so a module's code must all go in one file. In that case, you can use regions to similarly separate a group of related routines and make the code easier to read.

Conditional compilation statements allow you to include or exclude code from the program's compilation. The basic conditional compilation statement is similar to a multiline If Then Else statement. The following code shows a typical statement. If the value condition1 is True, the code in code_block_1 is included in the compiled program. If that value is False but the value condition2 is True, the code in code_block_2 becomes part of the compiled program. If neither condition is True, the code in code_block_3 is included in the program.

#If condition1 Then
    code_block_1 ...
#ElseIf condition2 Then
    code_block_2 ...
#Else
    code_block_3 ...
#End if

It is important to understand that the code not included by the conditional compilation statements is completely omitted from the executable program. At compile time, Visual Studio decides whether or not a block of code should be included. That means any code that is omitted does not take up space in the executable program. It also means that you cannot set the execution statement to omitted lines in the debugger because those lines are not present.

In contrast, a normal If Then Else statement includes all the code in every code block in the executable program, and then decides which code to execute at runtime.

Because the conditional compilation statement evaluates its conditions at compile time, those conditions must be expressions that can be evaluated at compile time. For example, they can be expressions containing values that you have defined using compiler directives (described shortly). They cannot include values generated at runtime (such as the values of variables).

In fact, a conditional compilation statement evaluates its conditions at design time, so it can give feedback while you are writing the code. For example, if Option Explicit is set to On, Visual Basic flags the following assignment statement as an error. Because the first condition is True, the variable X is declared as a string. Option Explicit On disallows implicit conversion from an integer to a string, so the IDE flags the statement as an error.

#If True Then
    Dim X As String
#Else
    Dim X As Integer
#End If
    X = 10

That much makes sense, but it's also important to realize that the code not included in the compilation is not evaluated by the IDE. If the first condition in the previous code were False, the code would work properly because variable X would be declared as an integer. The IDE doesn't evaluate the other code, so it doesn't notice that there is an error if the condition is False. You probably won't notice the error until you try to actually use the other code.

You can set conditional compilation constants in two main ways: in code and in the project's compilation settings.

#Const UserType = "Clerk"

#If UserType = "Clerk" Then
    ' Do stuff appropriate for clerks ...
    ...
#ElseIf UserType = "Supervisor" Then
    ' Do stuff appropriate for supervisors ...

...
#Else
    ' Do stuff appropriate for others ...
    ...
#End if

#If UseFastAlgorithm Then
    MessageBox.Show("Fast")
#Else
    MessageBox.Show("Slow")
#End If

#Const UseFastAlgorithm = True

#If UseFastAlgorithm Then
    MessageBox.Show("Fast")
#Else
    MessageBox.Show("Slow")
#End if

Setting Constants with the Project's Compilation Settings

To set constants with the project's compilation settings, open Solution Explorer and double-click My Project. Select the Compile tab and click its Advanced Compile Options button to open the Advanced Compiler Settings dialog box shown in Figure 14-4. Enter the names and values of the constants in the "Custom constants" text box. Enter each value in the form ConstantName=Value, separating multiple constants with commas.

Figure 14.4. Use the Advanced Compiler Settings dialog box to define compilation constants.

Constants that you specify on the Advanced Compiler Settings dialog box are available everywhere in the project. However, your code can redefine the constant using a #Const directive. The constant has the new value until the end of the file or until you redefine it again.

Example program CompilerConstantsSettings, which is available for download on the book's web site, includes constants set on this dialog and code to check their values.

DEBUG

Normally when you make a debug build, Visual Basic sets the DEBUG constant to True. When you compile a release build, Visual Basic sets DEBUG to False. The Configuration Manager lets you select the Debug build, the Release build, or other builds that you define yourself.

After you have activated the Configuration Manager, you can open it by clicking the project in the Solution Explorer and then selecting the Build menu's Configuration Manager command. Figure 14-5 shows the Configuration Manager. Select Debug or Release from the drop-down list, and click Close.

Figure 14.5. Use the Configuration Manager to select a Debug or Release build.

THE MISSING MANAGER MYSTERY

If the Configuration Manager is not available in the Build menu, open the Tools menu and select the Options command. Open the Projects and Solutions node's General entry, and select the "Show advanced build configurations" check box.

When the DEBUG constant is True, the Debug object's methods send output to the Output window. When the DEBUG constant is not True, the Debug object's methods do not generate any code, so the object doesn't produce any output. This makes the Debug object useful for displaying diagnostic messages during development and then hiding the messages in release builds sent to customers.

The following sections describe some of the Debug object's most useful properties and methods.

Assert

The Debug.Assert method evaluates a Boolean expression and, if the expression is False, displays an error message. This method can optionally take as parameters an error message and a detailed message to display. The following code shows how a program might use Debug.Assert to verify that the variable NumEmployees is greater than zero:

Debug.Assert(NumEmployees > 0, _
    "The number of employees must be greater than zero.", _
    "The program cannot generate timesheets if no employees are defined")

Example program EmployeeAssert, which is available for download on the book's web site, demonstrates this Debug.Assert statement.

If NumEmployees is zero, this statement displays an error dialog that shows the error message and the detailed message. It also displays a long stack dump that shows exactly what code called what other code to reach this point of execution. Only the first few entries will make sense to practically anyone because the stack dump quickly moves out of the application's code and into the supporting Visual Basic libraries that execute the program.

The dialog also displays three buttons labeled Abort, Retry, and Ignore. If you click the Abort button, the program immediately halts. If you click Retry, the program breaks into the debugger, so you can examine the code. If you click Ignore, the program continues as if the Assert statement's condition was True.

A good use for the Assert method is to verify that a routine's parameters or other variable values are reasonable before starting calculations. For example, suppose that the AssignJob subroutine assigns a repairperson to a job. The routine could begin with a series of Assert statements that verify that the person exists, the job exists, the person has the skills necessary to perform the job, and so forth. It is usually easier to fix code if you catch these sorts of errors before starting a long calculation or database modification that may later fail because, for example, the repairperson doesn't have the right kind of truck to perform the job.

If the DEBUG constant is not True, the Assert method does nothing. This lets you automatically remove these rather obscure error messages from the compiled executable that you send to customers. The dialog with its messages and stack dump is so technical that it would terrify many users anyway, so there's no point inflicting it on them.

You should take some care when deciding what tests should be placed in Assert statements so that they are removed from the compiled executable. For example, suppose you use Assert to verify that a string entered by the user contains a valid value. When you run the compiled executable, this test is removed, so the program does not protect itself from bad data. When you use Assert to verify a condition, you must be certain that the program can run safely if the Assert statement is removed and the condition fails.

If the program cannot run safely when the condition fails, you should also add code to protect it even in the final compiled version.

Fail

The Debug.Fail method displays an error message just as Debug.Assert does when its Boolean condition parameter is False.

IndentSize, Indent, Unindent, and IndentLevel

These properties and methods determine the amount of indentation used when the Debug object writes into the Output window. You can use them to indent the output in subroutines to show the program's structure more clearly.

The IndentSize property indicates the number of spaces that should be used for each level of indentation. The IndentLevel property determines the current indentation level. For example, if IndentSize is 4 and IndentLevel is 2, output is indented by eight spaces.

The Indent and Unindent methods increase and decrease the indentation level by one.

Write, WriteLine, WriteIf, and WriteLineIf

These routines send output to the Output window. The Write method prints text and stops without starting a new line. WriteLine prints text and follows it with a new line.

The WriteIf and WriteLineIf methods take a Boolean parameter and act the same as Write and WriteLine if the parameter's value is True.

#If CONFIG = "Debug" Then
    ' Do stuff for a Debug build ...
#ElseIf CONFIG = "Release" Then
    ' Do stuff for a Release build ...
#ElseIf CONFIG = "InterimBuild" Then
    ' Do stuff for a custom InterimBuild ...
#Else
    MessageBox.Show("Unknown build type")
#End if

#Const DEBUG_LEVEL = 2

    Private Function IsPhoneNumberValid(ByVal phone_number As String) As Boolean
#If DEBUG_LEVEL >= 1 Then
        Debug.WriteLine("Entering IsPhoneNumberValid(" & phone_number & ")")
        Debug.Indent()
#End If
        ' Check for a 7-digit phone number.
#If DEBUG_LEVEL >= 2 Then
        Debug.WriteLine("Checking for 7-digit phone number")
#End If
        Dim is_valid As Boolean = _
            phone_number Like "###-####"

        If Not is_valid Then
#If DEBUG_LEVEL >= 2 Then
            Debug.WriteLine("Checking for 10-digit phone number")
#End If
            is_valid = phone_number Like "###-###-####"
        End If

#If DEBUG_LEVEL >= 1 Then
        Debug.Unindent()
        Debug.WriteLine("Leaving IsPhoneNumberValid, returning " & is_valid)
#End If
        Return is_valid
    End Function
                                                  

Entering IsPhoneNumberValid(123-4567)
    Checking for 7-digit phone number
Leaving IsPhoneNumberValid, returning True

Visual Studio uses namespaces to categorize code. A namespace can contain other namespaces, which can contain others, forming a hierarchy of namespaces.

You can define your own namespaces to help categorize your code. By placing different routines in separate namespaces, you can allow pieces of code to include only the namespaces they are actually using. That makes it easier to ignore the routines that the program isn't using. It also allows more than one namespace to define items that have the same names.

For example, you could define an Accounting namespace that contains the AccountsReceivable and AccountsPayable namespaces. Each of those might contain a subroutine named ListOutstandingInvoices. The program could select one version or the other by calling either Accounting.AccountsReceivable.ListOutstandingInvoices or Accounting.AccountsPayable.ListOutstandingInvoices.

You can only use the Namespace statement at the file level or inside another namespace, not within a class or module. Within a namespace, you can define nested namespaces, classes, or modules.

The following example defines the AccountingModules namespace. That namespace contains the two classes PayableItem and ReceivableItem, the module AccountingRoutines, and the nested namespace OrderEntryModules. The AccountingRoutines module defines the PayInvoice subroutine. All the classes, modules, and namespaces may define other items.

Namespace AccountingModules
    Public Class PayableItem
         ...
    End Class

    Public Class ReceivableItem
         ...
    End Class

    Module AccountingRoutines
        Public Sub PayInvoice(ByVal invoice_number As Long)

...
        End Sub
         ...
    End Module

    Namespace OrderEntryModules
        Public Class OrderEntryClerk
             ...
        End Class
         ...
    End Namespace
End Namespace

Code using a module's namespace does not need to explicitly identify the module. If a module defines a variable or routine that has a unique name, you do not need to specify the module's name to use that item. In this example, there is only one subroutine named PayInvoice, so the code can invoke it as AccountingModules.PayInvoice. If the AccountingModules namespace contained another module that defined a PayInvoice subroutine, the code would need to indicate which version to use as in AccountingModules.AccountingRoutines.PayInvoice.

Although modules are transparent within their namespaces, nested namespaces are not. Because the nested OrderEntryModules namespace defines the OrderEntryClerk class, the code must specify the full namespace path to the class, as in the following code:

Dim oe_clerk As New AccountingModules.OrderEntryModules.OrderEntryClerk

You can use an Imports statement to simplify access to a namespace inside a file. For example, suppose that you are working on the GeneralAccounting project that has the root namespace GeneralAccounting. The first statement in the following code allows the program to use items defined in the AccountingModules namespace without prefixing them with AccountingModules. The second statement lets the program use items defined in the AccountingModules nested namespace OrderEntryModules. The last two lines of code declare variables using classes defined in those namespaces.

Imports GeneralAccounting.AccountingModules
Imports GeneralAccounting.AccountingModules.OrderEntryModules
...
Private m_OverdueItem As PayableItem   ' In the AccountingModules namespace.
Private m_ThisClerk As OrderEntryClerk ' In the namespace
                                       ' AccountingModules.OrderEntryModules.

Comments can help other developers (or you at a later date) understand the program's purpose, structure, and method. You start a comment by typing a single quotation mark (') that is not inside a quoted string. All of the characters starting at the quote and continuing until the end of the line are part of the comment and are ignored by Visual Basic.

If a line with a comment ends with a line continuation character (described shortly), Visual Basic ignores that character. That means the line is not continued onto the next line, so the comment ends with the current line. In other words, you cannot use line continuation characters to make a multi-line comment.

In the following code, the first declaration is followed by a comment. The comment ends with a line continuation character so you might expect the second declaration to be part of the comment. That is not the case. Because this can be misleading, you should not end comments with a line continuation character. The second statement declares and initializes a string using a value that contains a single quote. Because the quote is inside a quoted string, it becomes part of the string and does not start a comment. The next single quotation mark outside of the string begins a new comment.

Dim num_customers As Integer   ' The number of customers. _
                                 This doesn't work as a continued comment!
Dim product_name As String = "Bob's Miracle Code Fixer" ' The program's name.

If you want to continue a comment on the following line, you must use another comment character, as in the following example:

' Return True if the address is valid. This function checks the address
' format to see that it makes sense. It also looks up the ZIP code and
' verifies that the city is valid for that ZIP code. It does not verify
' that the street and street number exist.
Private Function IsAddressValid(ByVal address_text As String) As Boolean
     ...

To quickly comment or uncomment a large block of code, click and drag to select it using the mouse and then open the Edit menu's Advanced submenu. Select the Comment Selection command to comment out the selection or select Uncomment Selection to remove the comment characters from the front of the selection. Those commands are also available more conveniently as buttons in the Text Editor toolbar. Use the View menu's Toolbars submenu's Text Editor command to show or hide this toolbar.

Another way to quickly remove a chunk of code from the program is to surround it with compiler directives, as in the following code:

#If False Then
    Dim A As Integer
    Dim B As Integer
    Dim C As Integer
#End if

Use comments to make your code clear. Comments do not slow the executable program down (some superstitious developers think they must slow the code because they make the file bigger), so there's no good reason to exclude them.

A normal comment is just a piece of text that gives information to a developer trying to read your code. XML comments let you add some context to a comment. For example, you can mark a comment as a summary describing a subroutine.

Visual Studio automatically extracts XML comments to build an XML file describing the project. This file displays the hierarchical shape of the project, showing comments for the project's modules, namespaces, classes, and other elements.

The result is not particularly easy to read, but you can use it to automatically generate more useful documentation such as reports or web pages.

You can place a block of XML comments before code elements that are not contained in methods. Generally, you use them to describe a module, class, variable, property, method, or event.

To begin a comment block, place the cursor on the line before the element you want to describe and type three single quotes ('''). Visual Studio automatically inserts a template for an XML comment block. If the element that follows takes parameters, it includes sections describing the parameters, so it is in your best interest to completely define the parameters before you create the XML comment block. (Otherwise you'll need to add the appropriate comment sections by hand.)

The following code shows the XML comment block created for a simple subroutine. It includes a summary area to describe the subroutine, two param sections to describe the subroutine's parameters, and a remarks section to provide additional detail.

''' <summary>
'''
''' </summary>
''' <param name="jobs"></param>
''' <param name="employees"></param>
''' <remarks></remarks>
Public Sub AssignJobs(ByVal jobs() As Job, ByVal employees() As Employee)

End Sub

Note that XML elements can span multiple lines, as the summary element does in this example.

You can add more XML comment sections to the block simply by typing them, following the convention that they should begin with three single quotes. For example, the following code adds some content for the comments in the previous code and an extra WrittenBy element that contains a date attribute:

''' <summary>
''' Assigns jobs to employees, maximizing the total value of jobs assigned.
''' </summary>
''' <param name="jobs">The array of Jobs to assign.</param>
''' <param name="employees">The array of Employees to assign.</param>
''' <remarks>The full assignment is not guaranteed to be unique.</remarks>
''' <WrittenBy date="7/24/10">Rod Stephens</WrittenBy>
Public Sub AssignJobs(ByVal jobs() As Job, ByVal employees() As Employee)

End Sub

The following code shows the beginning of an application that assigns jobs to employees. The project contains two files, a form named Form1.vb and a code module named Module1.vb. The form contains very little code. The code module defines the Job and Employee classes and the AssignJobs subroutine. Each of these has an XML comment block.

Public Class Form1
    Private m_Jobs() As Job
    Private m_Employees() As Employee
End Class

Module Module1
    Public Class Job
        Public JobNumber As Integer
        ''' <summary>
        ''' A list of skills required to perform this job.
        ''' </summary>
        ''' <remarks>Represent required equipment as skills.</remarks>
        Public SkillsRequired As New Collection
        ''' <summary>
        ''' The value of this job.
        ''' </summary>
        ''' <remarks>Higher numbers indicate more priority.</remarks>
         Public Priority As Integer
    End Class

Public Class Employee
    Public FirstName As String
    Public LastName As String
    ''' <summary>
    ''' A list of skills this employee has.
    ''' </summary>
    ''' <remarks>Represent special equipment as skills.</remarks>
    Public Skills As New Collection
    End Class

    ''' <summary>
    ''' Assigns jobs to employees.
    ''' </summary>
    ''' <param name="jobs">Array of Jobs to assign.</param>
    ''' <param name="employees">Array of Employees to assign jobs.</param>
    ''' <remarks>Maximizes total value of jobs assigned.</remarks>
    ''' <WrittenBy date="7/26/04">Rod Stephens</WrittenBy>
    Public Sub AssignJobs(ByVal jobs() As Job, ByVal employees() As Employee)

    End Sub
End Module
                                                  

In addition to providing documentation for your use, XML comments let the Object Browser provide additional information about your code. Figure 14-6 shows the Object Browser describing the Job class's SkillsRequired property. The area on the lower right shows the property's XML summary and remarks sections. This project's name is AssignJobs, its root namespace is AssignJobs, and the Job class is contained in the JobStuff module, so the complete path to the Job class shown in the tree view on the left is AssignJobs (project)

Figure 14.6. The Object Browser displays an item's XML summary and remarks sections.

When you compile the application, Visual Studio extracts the XML comments and places them in an XML file with the same name as the executable file in the project's binDebug directory. The following text shows the result. If you look through the document carefully, you can pick out the XML comments.

<?xml version="1.0"?>
<doc>
<assembly>
<name>
AssignJobs
</name>
</assembly>
<members>
<member name="F:AssignJobs.JobStuff.Job.SkillsRequired">
    <summary>
 A list of skills required to perform this job.
 </summary>
    <remarks>Represent required equipment as skills.</remarks>
</member><member name="F:AssignJobs.JobStuff.Job.Priority">
    <summary>
 The value of this job.
 </summary>

<remarks>Higher numbers indicate more priority.</remarks>
</membergt;<member name="F:AssignJobs.JobStuff.Employee.Skills">
    <summary>
 A list of skills this employee has.
 </summary>
    <remarks>Represent special equipment as skills.</remarks>
</member><member name="M:AssignJobs.JobStuff.AssignJobs(
AssignJobs.JobStuff.Job[],AssignJobs.JobStuff.Employee[])">
    <summary>
 Assigns jobs to employees.
 </summary>
    <param name="jobs">Array of Jobs to assign.</param>
    <param name="employees">Array of Employees to assign jobs.</param>
    <remarks>The assignment maximizes total value of jobs assigned.</remarks>
    <WrittenBy date="1/13/07">Rod Stephens</WrittenBy>
</member>
</members>
</doc>

Example program AssignJobs, which is available for download on the book's web site, defines job assignment classes that you can view with the Object Browser. If you compile the program (which actually doesn't do any job assignment, it just defines the classes), you can examine its XML documentation.

Line continuation characters let you break long lines across multiple shorter lines so that they are easier to read. To continue a line, end it with a space followed by an underscore (_). Visual Basic treats the following code as if it were all on one long line:

Dim background_color As Color = _
    Color.FromName( _
        My.Resources.ResourceManager.GetString( _
            "MainFormBackgroundColor"))

As the previous section explains, you cannot continue comments. A comment includes any space and underscore at the end of its line so the comment does not apply to the following line.

You can break a line just about anywhere that a space is allowed and between program elements. For example, you can break a line after the opening parenthesis in a parameter list, as shown in the following code:

AReallyReallyLongSubroutineNameThatTakesFiveParameters( _
    parameter1, parameter2, parameter3, parameter4, parameter5)

You cannot break a line inside a quoted string. If you want to break a string, end the string and restart it on the next line, as in the following example:

Dim txt As String = "To break a long string across multiple lines, " & _
    "end the string, add the line continuation character " & _
    "(space + underscore) " & _
    "and restart the string on the next line."

Visual Basic does not enforce its usual indentation rules on continued lines, so you can indent the lines in any way you like to make the code's structure more clear. For example, many programmers align parameters in long subroutine calls:

DoSomething( _
    parameter1, _
    parameter2, _
    parameter3)

Visual Basic can also guess where you are continuing a line even if you don't use the line continuation character, at least sometimes. For example, Visual Basic can figure out that the statement shown in the following code isn't complete until the final line so it treats all of this code as if it were written on a single long line.

Dim background_color As Color =
    Color.FromName(
        My.Resources.ResourceManager.GetString(
            "MainFormBackgroundColor"
        )
    )

Visual Basic does not allow implicit line continuation in all cases, however. For example, in the following code the "Next i" statement is split across two lines. Because a Next statement's variable name is optional, Visual Basic doesn't know that the following i is required so it doesn't look for it.

For i As Integer = 1 To 10

Next
    i

In fact, you can't break the statement "For i As Integer = 1 To 10" at any point without a line continuation character or Visual Basic gets confused.

Some places that Visual Basic does allow implicit line continuation include:

The following code shows a few examples:

<
    ComClass()
>
Public Class Employee
    Public Function CalculateStuff(
        ByVal v1 As Integer,
        ByVal v2 As Integer
    )

        Dim a As Integer =
            Math.Max(
                v1,
                v2 +
                12
            )
        Return a
    End Function

     ...
End Class

a = Math.Max(b, c + d)

Not only can you break a long statement across multiple lines, but you can also join short statements on a single line. To use two statements on a single line, separate them with a colon (:). The following line of code contains three statements that store the red, green, and blue components of a form's background color in the variables r, g, and b:

r = BackColor.R : g = BackColor.G : b = BackColor.B

Line joining is most useful when you have many lines in a row that all have a very similar structure. By scanning down the lines, you can tell if there are differences that may indicate a bug.

Use line joining with some caution. If the statements are long, or if you have a series of joined lines with dissimilar structure, combining lots of statements on a single line can make the code harder to read. If the code is easier to read with each statement on a separate line, write the code that way. Using more lines doesn't cost extra or make the code run any slower.

You can place a label to the left of any line of code. The label can be either a name or a number, followed by a colon. The following code defines three labels. The first is named DeclareX and marks the declaration of the variable X. The second has value 10 and is located on a line containing a comment. The third label, named Done, labels a blank line.

DeclareX: Dim X As Single
10:       ' Do something here.
Done:

You must label a line if you will later want to jump to that line. For example, the GoTo, On Error GoTo, and Resume statements can make code jump to a labeled line. These are less useful in Visual Basic .NET than they were in Visual Basic 6 and previous versions that didn't have structured error handling (the Try Catch block), but they are still available.