InformIT: Sams Teach Yourself Visual Basic 6 in 24 Hours

A Short Detour: Remarks

Figures 6.5 and 6.6 show two new program statements you've not yet seen. Two remark statements appear in each figure. Remarks help both you and other programmers who might modify and update your Visual Basic applications in the future. Remarks offer descriptive messages that explain in English (or whatever language you prefer) what's going on in the program's code.

It's said that a program is written once and read many times. That saying is true because of the nature of applications. Often, you'll write a program that helps you or your business compute required calculations and keep track of daily transactions. Over time, requirements change. Businesses buy and sell other businesses, the government changes its reporting and taxing requirements, and people's needs change. You should realize that after you write and implement a program, you will make modifications to that program later. If you use the program in a business, you'll almost certainly make many modifications to the program to reflect changing conditions.

TIP

If you program for someone else or as part of a team, the chances are high that others will modify the programs that you write and that you'll modify programs that other programmers write. Therefore, as you write programs, think about the future modifications that you and others will make. Write your programs clearly, using ample spacing and indentation, and add remarks that explain complex sections of code.

The most useful remarks are those that point out assumptions made when doing the complex sections of code. For example, in an insurance program, you might identify the actuarial table that was used to provide variables in a computation.

A remark is a message that you put inside a program's code. Programmers concerned with maintenance know that ample remarks help clarify code and aid future maintenance. Visual Basic completely ignores any and all remarks because those remarks are for people looking at your program code. Users don't see remarks because users don't see the program's code; rather, users see a program's output.

Programmers often add remarks to their programs for the following purposes:

To state the programmer's name and the date that the program was written.
To describe in the general section the overall goal of the program. (The general section appears before all the program's procedures and is the location Hour 5, "Putting Code into Visual Basic," described when it talked about declaring global variables.)
To describe at the top of every procedure the overall goal of that procedure.
To explain tricky or difficult statements so that others who modify the program later can understand the lines of code without having to decipher cryptic code.

Even if you write programs for yourself, and if you are the only one who will modify your programs, you should still add remarks to your programs. Weeks or months after you write a program, you'll have forgotten the exact details of the program, and remarks that you interspersed throughout the code will simplify your maintenance and help you find the code that you need to change.

Add remarks to your program so that you and others can more quickly grasp the nature of the program and can make modifications to it more easily when needed. Visual Basic supports two kinds of remarks:

Remarks that begin with the Rem statement
Remarks that begin with the apostrophe (')

The Rem statement is more limiting than the apostrophe and isn't as easy to use. Nevertheless, you'll run across programs that use Rem statements, so you should learn how Rem works. Here is the format of the Rem statement:

Rem The remark's text

You can put anything you want in place of The remark's text . The following are examples of remarks:

Rem Programmer: Sanjaya Hettihewa, Date: Mar-27-1998
Rem
Rem This program supports the check-in and check-out
Rem  process for the dry-cleaning business.
Rem
Rem This event procedure executes when the user
Rem  clicks on the Exit command button. When pressed,
Rem  this event procedure closes the program's data
Rem  files, prints an exception report, and terminates
Rem  the application

The first of these remark sections consists of a one-line remark that tells the programmer's name and the date that the program was last modified. If someone else must modify the program later, that person can find the original programmer if needed to ask questions about the program's code. The second remark describes the program's overall goal by starting with a high-level description of the program's purpose. The third remark might appear at the top of a command button's Click event procedure.

As you can see, you can add one or more lines of remarks depending on the amount of description needed at that point in the program. Visual Basic ignores all lines that begin with Rem. When someone looks at the program code later, that person will know who the programmer is, the date that the program was written, the overall purpose of the program, and the overall description of each procedure that includes a remark section.

Say that you used apostrophes in place of the Rem statement in the previous remarks. The following rewritten remarks demonstrate that the remarks are even more effective because Rem doesn't get in the way of each remark's text:

' Programmer: Sanjaya Hettihewa, Date: Mar-27-1998
'
' This program supports the check-in and check-out
' process for the dry-cleaning business.
'
' This event procedure executes when the user
' clicks on the Exit command button. When pressed,
' this event procedure closes the program's data
' files, prints an exception report, and terminates
' the application

The remarks don't have to go at the beginning of event procedures. You can place remarks between lines of code, as shown here:

Dim intRec As Integer
Rem Step through each customer record
For intRec = 1 To intNumCusts
' Test for a high balance
If custBal(intRec) > 5000 Then
Call PayReq
End If
Next intRec

You can place apostrophe remarks at the end of Visual Basic statements. By placing a remark to the right of certain lines of code, you can clarify the purpose of the code. Consider how the following code section uses a remark to explain a specific line of code:

a = 3.14159 * r * r   ' Calculate a circle's area

Perhaps only a mathematician could interpret the formula without the remark. The remark helps even non-mathematicians understand the purpose of the statement. There is no reason that you should have to re-examine code every time you look at it. By reading remarks, you can glean the code's purpose without taking the time to interpret the Visual Basic code.

The wrong kinds of remarks won't help clarify code, though, so don't overdo them. As a matter of fact, many lines of code need no remarks to explain their purpose. The following remark is redundant and wastes both your programming time and the time of anyone who may maintain the program later:

Dim Sales As Single   ' Define a variable named Sales

Examining InputBox() | Next Section

Previous Section