Visual Basic 6 Black Book
(Publisher: The Coriolis Group)
Author(s): Steven Holzner
ISBN: 1576102831
Publication Date: 08/01/98

Here’s an example showing how to set up a comment preceding a function named dblSquare():

'*****************************************************
' dblSquare()
' Purpose: Squares a number
' Inputs: sngSquareMe, the value to be squared
' Returns: The input value squared
'*****************************************************
Function dblSquare() (sngSquareMe As Integer) As Double
    dblSquare = sngSquareMe * sngSquareMe    'Use *, not ^2, for speed
End Function

---

TIP:  You might notice that dblSquare() takes a Single parameter and returns a Double value; that’s because squaring a Single can create a larger number, which might not fit into a Single value, or it can add more decimal places. Note also that we multiply the parameter sngSquareMe by itself to square it instead of using the exponentiation operator, because doing so saves a lot of processor time.

---

Note that it’s particularly important to list all the global variables a procedure uses or affects in this initial comment block, because they are not listed in the parameter list.

That completes our overview of the Visual Basic programming conventions. We’ll finish the chapter with a look at what we might call best coding practices, as targeted at Visual Basic. Through the years, some definite programming practices have proven themselves better than others, and we’ll take a look at some of them now before digging into the rest of the book.

Best Coding Practices In Visual Basic

The full construction of a commercial program is usually a project that involves many clear and definite steps. There have been whole volumes written on this topic, which are usually only interesting if you are a software project manager (or write computer books and have to know the details so you can write about them!). Such books get pretty involved, encompassing ideas like module coupling and cohesion, bottom-up composition, incremental integration, and much more.

On the whole, however, one can break the software design process into steps like these (note that the explanation of each step is very flexible; there is no one-size-fits-all here):

•  Requirements analysis—Identify the problem for the software to tackle.

•  Creating specifications—Determine what exactly the software should do.

•  Overall design—Break the overall project into parts, modules, and so on.

•  Detailed design—Design the actual data structures, procedures, and so on .

•  Coding—Go from PDL to code.

•  Debugging—Solve design-time, compilation, and obvious errors.

•  Testing—Try to break the software.

•  Maintenance—React to user feedback and keep testing.

Each of these steps may have many subparts, of course. (For example, the maintenance part may take up as much time as the rest of the project taken together.)

As the design process continues, a model of what the program does evolves. You use this model to get a conceptual handle on the software (while keeping in mind that models are usually flawed at some level). Keeping the model in mind, then, many programmers use a program design language to start the actual coding process.

Program Design Language

Everyone seems to think that programmers use flowcharts, but the reality is usually different (flowcharts are nice to show to nonprogrammers, though). One tool that commercial programmers do find useful is program design language (PDL). Although there are formal specifications for PDL, many programmers simply regard this step as writing out what a program does in English as a sort of pseudo-code.

For example, if we want to create a new function named dblSqrt() that returns a number’s square root, we might write its PDL this way in English, where we break what the function does into steps:

Function dblSqrt()
    Check if the input parameter is negative
        If the input parameter is negative, return -1
        If the input parameter is positive, return its square root
End Function

When you actually write the code, the PDL can often become the comments in that code; for example, here’s the completed function:

'*****************************************************
' dblSqrt()
' Purpose: Returns the passed parameter's square root
' Inputs: dblParameter, the parameter whose square root we need
' Returns: The input value's square root
'*****************************************************
Function dblSqrt(dblParameter As Double) As Double

    'Check if the input parameter is negative
    If dblParameter < 0 Then
        'If the input parameter is negative, return -1
        dblSqrt = -1

    Else
        'If the input parameter is positive, return its square root
        dblSqrt = Sqr(dblParameter)

    End If
End Function

In this way, developing your program using PDL, where every line of PDL has one (and only one) specific task, can be very useful. So much for overview—let’s turn to particulars that affect us as Visual Basic programmers.