Comments

[ LiB ]

I may have 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 tell me 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 filename 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$) WaitKey ;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 

NOTE

This program is way more complex than it needs to be. There isn't much sense in using functions and variables in a simple Hello World program. The only rea son I used functions and variables in this program is to demonstrate the use of comments.

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.

Figure 4.4. Hello World!

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 follows . 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 .

NOTE

Refresher : The Difference between a Declaration and a Definition

I use the terms definition and declaration a lot in this chapter, and now is as good a time as any to go over the difference again. A declaration simply refers to or states a function or variable, and a definition actually defines it. For example, the declaration of PrintString is PrintString(strng$). The actual definition, however, is

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

In summary, when I refer to the declaration of a function, I am talking about the call to it in code or the title of the function. When I refer to the definition of a function, I am talking about the actual code inside the function.

Before I define any functions, I always create a box that explains the function. In 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 functionit makes understanding them a heck of a lot easier.

[ LiB ]