Comments

I talked a little about comments previously, but I am going to explain them in depth now. Comments, as you know, are simply statements you write within your program to explain what you are doing. In a program, comments look like this:

Print "This is a statement.";this is a comment

Make sure you notice the semicolon before the comment. The semicolon is required for every comment; in fact, it is how a comment is identified to the compiler. Comments are used to explain how a part of a program works: it may define what a single statement does, or it may tell what a whole block of statements does. I use almost one comment every other line in my programs; it helps because I often forget what I was trying to do after I finish a program. When I come back a few days or weeks later, the comments are still there to help guide me through my code.

Comments aren’t only used to offer help for a single statement. I usually create a block of comments at the beginning of my programs to explain what the program

does. I often use a large box to draw my eyes toward it like this (the full listing for this program is named demo04-01.bb on the CD):

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; HelloWorld.bb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; By Maneesh Sethi;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; This program prints "Hello World to the screen.;;;;;
; There are no input variables required;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

As you can see, this box of comments is the intro to a HelloWorld program. I put a box like this at the top of most programs. It tells the reader four things: what the file name is, who the author is, what the purpose of the program is, and any extra info the user needs to use it.

There are some extra rows of information that you can add to the box. Maybe you want to tell the reader what version of the program this is, and you might want to reference others who helped you with it. Perhaps you have some special restrictions on the program (“this program does not run on Windows XP”), or something of that nature.

The next part of the program is the actual code. With comments, it might look something like this:

;VARIABLES
;The hello string to be printed on the screen
hellostr$ = "Hello World!";END VARIABLES

;MAIN PROGRAM
;Pass "hellostr$" to PrintString function
PrintString(hellostr$)

;Wait for five seconds before closing
Delay 5000
;END MAIN PROGRAM
;FUNCTIONS
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;Function PrintString(strng$);;;;;;;;;;;
;This function prints the variable strng$
;Parameters: strng$ - the string to be printed
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Function PrintString(strng$)
;Print str$ on screen
Print strng$
End Function
;END FUNCTIONS

And there you have it! A fully commented version of Hello World, as in Figure 4.4. Let’s take a look at some of these comments.

Pre-Program Comments

Before the actual main program, I create a few commented sections that I call the pre-program comments. This usually includes local variables, global variables, constants, array dimensions, and anything else that you declare before the program starts. For each section, I write a line of code that explains what is

following. For example, in demo04-01.bb, I created a section for variables. At the end of the declarations, I add a line of code that tells the reader that it is the end of the section (END VARIABLES in the Hello World example).

I also comment each variable individually to explain what it does specifically. Adding these simple lines of code makes it much easier to find out what a variable is named and what its value is simply by searching the top of a program.

Main Program Comments

I add some simple comments to the beginning of and inside the actual main program. At the beginning, I add a comment detailing the starting point of the actual program. I also add comments after statements, just as in the rest of the program.

Main program comments also tell where the main game loop begins and ends. I add those comments at the top and bottom of the While...Wend loop. Comments are usually included near function calls, such as the call to PrintScreen(strng$) in demo04-01.bb. The comments detail which function it calls and what the function does.

Function Comments

The function comments are written at the beginning of each and every function. I usually begin the function definitions after the end of the main program; consequently, I comment the ;FUNCTION header directly after ;END OF MAIN PROGRAM.

Function PrintString(str$)
Print str$ ;Print str$ on screen
End Function

Before I define any functions, I always create a box that explains the function. On demo04-01.bb the PrintString(strng$) function is commented like this:

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;Function PrintString(strng$);;;;;;;;;;;
;This function prints the variable strng$
;Parameters: strng$ - the string to be printed
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

As you can see, this block states the name of the function, its purpose, and its parameters. Make sure you add a block like this to the beginning of every function—it makes understanding them a heck of a lot easier.