| In addition to other naming conventions, we suggest carefully naming data structures and procedures. We also suggest specific conventions for indentation and commenting. Naming Data Structures The following subsections describe how we name other types of objects within projects, such as classes, interfaces, enumerations, and so on. Classes and Structures Although it is, again, a matter of contention, we suggest using nonprefixed names for classes (some developers insist in prefixing classes with C). We also suggest that you create property procedures for all properties within your classes (as opposed to using public variables), because this grants you greater flexibility as you continue to evolve your class implementation. Feel free to use Hungarian notation for any and all private data, but we suggest that you don't expose any public members with prefixed names. Here's an example: Public Class Customer Public Property Name() As String End Property ... End Class Interfaces Begin interface names with I. Here's an example: Interface ICustomers ... End Interface In this case, ICustomers defines an interface that would be implemented by other classes. Enumerations An enumeration should have a descriptive name, followed by the suffix Enum. Here's an example: Public Enum GridTypesEnum All = 0 ListOnly = 1 End Enum To use this enumeration, you could write code like this: Dim gt As GridTypesEnum = GridTypesEnum.All Constants Constant names should be uppercase with underscores (_) between words. This will help distinguish your constants from any other type that you might use in your application. Be sure to supply a data type for your constants of course, with Option Strict on, you won't be able to leave out the data type. If you do not type your constants, they will be of the type Object. Your constant declarations might look like this: Public Const TAB_ADDRESS As Integer = 0 Public Const TAB_PHONES As Integer = 1 Conditional Compile Constants For conditional compilation constants, use the prefix cc followed by all uppercase letters. Separate words with an underscore character, just like regular constants: #If ccDEMO Then ' Perform some code here #End If Exceptions in Try/Catch Blocks Although many error-handling examples you'll see use e as the name of the Exception object handled within a Catch block, you'll find that this name conflicts with the parameter passed into many event-handling procedures. We suggest using the exp prefix (or simply the name exp, on its own) to avoid the conflict. Here's an example: Try ... Catch exp As Exception ... End Try If you create your own classes, inheriting from the Exception object, make sure you follow the same convention used by Microsoft: Give the class a meaningful name, followed by Exception. For example, your exception class that handles the "file too large" exception might be named FileTooLargeException. Naming Procedures Naming procedures comprise another area in which careful planning will help make your applications more understandable and more maintainable. Selecting a standard within your development organization will make it easier for all your developers to work together. We've gathered a list of suggestions, and we've found that these suggestions make our development tasks go more smoothly. When naming procedures, we follow these rules in general: Use mixed case, where each word in the procedure is capitalized. Begin functions and procedures with a noun. Follow the noun with the action that will be performed on the object represented by the noun. Avoid using underscores in your function names, because it becomes hard to determine which procedures are yours and which are event-handling procedures. Here are some examples of procedure names that follow these conventions: FormShow FormInit StateLoad EmployeeLoad As you can see, these examples place the noun, or object, first. This convention mirrors the way that in object-oriented languages the object name is placed first, followed by the method or action you wish to perform on that object. Objects are always nouns, and actions are verbs. Therefore, we suggest you follow this coding style when creating names for your procedures. TIP This coding style has an added benefit. When you use a cross-referencing tool or are looking in the Procedure drop-down box in Visual Studio .NET, you will see all functions that operate on a particular object grouped in one place. Because you've named your procedures so that all the actions associated with a given object begin with the name of that object, they'll all be sorted together within the list.
Commenting Your Code All procedures and functions should begin with a brief comment describing the functional characteristics of the routine (that is, what it does). This description should not describe the implementation details (that is, how the procedure does its work) because the implementation often changes over time, resulting in unnecessary comment-maintenance work or worse yet erroneous comments. The worst possible case is one in which the procedure comments describe how the procedure works, but the comments and the actual procedure don't match. The code itself and any necessary inline or local comments should describe the implementation. Here are some additional suggestions involving comments: Parameters passed to a routine should be described if their use isn't obvious and when the routine expects the parameters to be in a specific range. (We also suggest the use of the Debug.Assert method, if it's important that parameters meet specific criteria.) Function return values and global variables that are changed by the routine (especially through reference parameters) must be described at the beginning of each procedure. Every nontrivial variable declaration should include an inline comment describing the use of the variable being declared. Variables, controls, and routines should be named clearly enough that inline commenting is only needed for complex or nonintuitive implementation details. Indentation Consistent code indentation can mean the difference between easily readable code and a hopeless nightmare. Happily, indentation has become a nonissue in Visual Studio .NET. If you allow Visual Studio .NET to perform its smart indenting, it will take care of the indentation for you. We strongly suggest that you allow Visual Studio .NET to handle the indentation chores. The standard indentation depth is four characters, and we don't see any reason to change it to a larger value. For the purposes of fitting more code into the limited space in this book, we've set this value to 2 in many cases. The good news is that it doesn't matter: If you simply select an entire procedure and then press Shift[PLUS]Tab, Visual Studio .NET will reformat the code for your particular tab setting, making it easy to adapt code formatted for a different tab size to your own preferences. | 
