Developer

Standards for menus and formatting make VB code more readable

Readable, easy-to-understand programs will help you avoid problems and make your team more productive. See how these Visual Basic standards for variable qualifiers, menus, formatting, and commenting may mean fewer headaches down the road.


Coding standards can improve the quality of your work and help make your team more efficient and effective. In "VB programming standards lead to better code,"  we discussed some coding standards and naming conventions for controls, variables, constants, enumerations, and procedures. To improve the readability of your Visual Basic programs even further, we’ll explore some suggested standards for variable qualifiers, menus, code formatting, and commenting.

Variable qualifiers
Often, projects contain variables that are related to one another. So your variables should be named in a way that makes the related information easy to find. For example, if you are retrieving information about a customer, such as first name and last name, use Customer as a standard qualifier for naming all variables related to Customer. Your qualifier will go right after the variable data type prefix—for example, strCustomerFirst and strCustomerLast—to denote that both variables relate to information gathered about a customer. Use the common variable qualifiers listed in Table A for naming related variables.

Table A
Suggested prefixes for frequently used controls


Menus
All menus should have the standard mnu prefix. Menu control prefixes should also include an additional prefix for each level of nesting, with the final menu caption at the end of the name string. For example, if your application has a top-level menu called File and submenu items Save and Print under it, assign the names mnuFile, mnuFileSave, and mnuFilePrint to make it obvious that the Save and Print menu items are under the File menu. If under File | Save you also have Excel and Text, call the submenus mnuFileSaveExcel and mnuFileSaveText.

Code formatting and commenting conventions
The addition of indents and comments can greatly improve the readability of your code. Properly used, indents can make it easy for someone reading your program to quickly identify the program structures. In fact, it can help reveal bugs or unnecessarily complex portions of the code before you ever run the program.

Code formatting
In general, your code should be easy for you and others to read. If you don't indent your statements, it is practically impossible to make sense of what you’re doing.

When you format your code, you should:
  • Make it easy to read and to understand.
  • Reduce the work necessary to understand structural constructs.
  • Make the structure of code as self-documenting as possible.
  • Indent continuation lines.
  • Use indentation to show organizational structure.

In other words, by formatting the code, it should be clear where various elements such as decision structures begin and end. If there is an else, you should be able to quickly identify the code that will execute for each portion of the if-else branch. More specifically, you should indent:
  • After an If statement when an End If is used.
  • After an Else statement.
  • After a Select Case statement.
  • After a Case statement.
  • After a Do statement.
  • Successive lines of a statement that has been split with the line continuation character.
  • After a With statement.
  • After calling an Edit or AddNew method of a Recordset object. The Update or CancelUpdate method should appear at the same level of indention as the Edit or AddNew statement.
  • After a BeginTrans method call.
  • In the declarations section of a module.
  • In the bodies of user-defined data type declarations.
  • In the bodies of enumeration declarations.
  • Code that is subordinate to a line label. Visual Basic doesn't allow you to indent labels, and this works to your advantage. If you indent the entire highest-level code one tab stop from the left side of the code window, the labels within the procedure will stand out because they are left-aligned in the code window.

In addition, you should use white space to group related statements. Insert a blank line:
  • Before and after each If…Then.
  • Before and after each Select Case.
  • Before and after each loop.
  • After declaring a block of variables.
  • Between groups of statements that perform a step in an overall task.

Code commenting
Most VB programmers don't use enough comments to clearly document their code. This is not only a problem for others who have to understand and modify your code, but it's also a problem for you when you read your own code months after you wrote it. You’ll be doing yourself and others down the road a big favor if you start commenting your code today.

Code comments should describe the purpose of the code and the logic behind it. Here are some pointers:
  • Comment before writing code. It's always a good idea to do some planning before you start writing. If you create comments before you start writing the code, you can create an outline of the steps you will perform in a procedure. Once that is done, just fill in the code between your comments and modify them if necessary.
  • Make your comments readable. (Use proper English, use complete sentences, and avoid abbreviations.)
  • Give each procedure a comment header, which includes the purpose, parameters, and return value of a procedure. You can also include other information, such as the author and date of creation.
  • Never document the implementation in the header because it changes often. Instead, use inline comments to document code processes.
  • Make sure all procedures/functions begin with a short comment that describes what the procedure/function does (header). Of course, not every line of code needs to be preceded by a comment line—some things are self-explanatory.
  • Describe any arguments that are passed to procedures and functions and return values.
  • Write a couple of lines explaining the purpose of each function/procedure right after their declaration. For example:
Private function CalculateLoanInterestRate (IngLoanAmount as Long)
    ‘This function calculates and returns the interst rate for the loan based on the
    ‘Loan Amount IngLoanAmount
    …
    End Function


 
  • Comment separate processes within your functions/procedures; explain what the next set of lines is doing.

  • Use the following structure for procedure/function headers:

    Purpose—Describe what is done in the procedure/function.

    Inputs—List each argument expected by procedure/function.

    Returns—Explain the values returned by a function.

    It’s cheaper to pay now
    The suggested standards here do take some time to implement. It also takes time to review the code to ensure that the standard is being adhered to. If these standards represent a significant departure from the normal activities of the group, there may even be some trauma associated with the change. Remember, however, inconsistent, hard-to-read code will exact an even higher price on your team later. And odds are, the problems caused by sloppy programming styles will hit you at a time when you can least afford to deal with them.

    At the very least, save yourself the cost of a bottle of aspirin. Get your team coding to some standard today.

    Editor's Picks