Microsoft Office 2000/Visual Basic Programmer's Guide

Naming Functions and Subroutines

A well-written procedure performs a single specific task and is named to identify the task performed. If you find it difficult to give a specific name to a procedure because it is performing more than one task, consider breaking the procedure down into multiple procedures so that each discrete piece of functionality can be clearly identified.

When naming a procedure, you should use the NounVerb or VerbNoun style to create a name that clearly identifies what the procedure does. It is not necessary to use a prefix or suffix to specify the data type of the return value. Keep in mind that when you store related procedures in the same module, the Procedures box in the Code window will display those procedures alphabetically. If you stored all your data access code in a module named modDataAccessCode, you could use the NounVerb naming style so that related procedures are listed together. For example, the CustomerAdd, CustomerDelete, and CustomerUpdate procedures would all be displayed together in the Procedures box.

When you are creating procedures that use arguments, use argument names that adhere to your variable-naming convention. For example, the following procedure uses arguments consisting of three strings, an integer, and a Boolean value:

Function RemoveString(ByVal strSource As String, _
                      strStart As String, _
                      strEnd As String, _
                      Optional intEndCount As Integer = 0, _
                      Optional blnReturnChunk As Boolean = False) As String

   .
   .
   .
End Function

The RemoveString procedure is available in the modAdditionalSamples module in FormattingExamples.doc in the ODETools\V9\Samples\OPG\Samples\CH03 subfolder on the Office 2000 Developer CD-ROM.

When you are calling a built-in or custom method or procedure that accepts optional arguments, always use named arguments instead of positional arguments. Named arguments make your code easier to understand, debug, and maintain. A named argument is an argument name followed by a colon and an equal sign (:=), followed by the argument value. When you use named arguments, you don't have to include placeholders for optional arguments not passed to the procedure. The first line in the following example shows how to call a custom procedure using positional arguments. The second line shows how to call the same procedure using named arguments.

strModifiedString = RemoveString(strOriginalString, strStartHere, _
   strEndHere, , True)

strModifiedString = RemoveString(strSource:=strOriginalString, _
   strStart:=strStartHere, strEnd:=strEndHere, blnReturnChunk:=True)

The next example shows how to use named arguments to call the Open method of the Word Documents collection. The Open method accepts up to 10 arguments, but only the FileName argument is required.

Application.Documents.Open ReadOnly:=True, FileName:="AUTOSHAPE.DOC", _
   Format:=wdOpenFormatAuto

If an argument uses a value that represents a built-in enumerated constant, declare the argument's data type by using the enumerated constant name. For example, if you have an argument that is used to specify one of the seven Outlook item types, declare the argument As Outlook.OlItemType rather than As Integer. Using this technique means you don't have to validate the argument that is passed to the procedure because by definition the argument value can contain only an existing Outlook item type. For example:

Function CreateNewItemB(intItemType As Outlook.OlItemType, _
                        Optional strName As String = "")
   Dim olApp         As New Outlook.Application
   Dim olNewItem   As Object
   
   Select Case intItemType
      Case olMailItem
         Set olNewItem = olApp.CreateItem(olMailItem)
      Case olAppointmentItem
         Set olNewItem = olApp.CreateItem(olAppointmentItem)
      Case olContactItem
         Set olNewItem = olApp.CreateItem(olContactItem)
      Case olTaskItem
         Set olNewItem = olApp.CreateItem(olTaskItem)
      Case olNoteItem
         Set olNewItem = olApp.CreateItem(olNoteItem)
      Case Else
   End Select
   .
   .
   .
End Function

The CreateNewItemB procedure is available in the modAdditionalSamples module in FormattingExamples.doc in the ODETools\V9\Samples\OPG\Samples\CH03 subfolder on the Office 2000 Developer CD-ROM.