Any topic

Liberty BASIC - Help Online

Documenting BASIC Code

When writing very short and simple BASIC programs, it isn't usually difficult to grasp how they work when reading them days or even weeks later. When a program starts to get large then it can be much harder. There are things that the programmer (yes, you) can do to make BASIC programs more understandable.

VARIABLES - Liberty BASIC makes it easy to give your variables very meaningful names. Since a variable name can be as long as you like and because Liberty BASIC lets you use upper and lower case letters, variable names can be very meaningful.

For example:

let c = (a^2 + b^2) ^ 0.5

could better be expressed:

let lengthOfCable = (distanceFromPole ^ 2 + heightOfPole ^ 2) ^ 0.5

Both are valid Liberty BASIC code, but the second is easier to read and maintain.

BRANCH LABELS - Make sure that when you use goto that your branch labels describe the kind of activity your BASIC program performs after the label. For example if you are branching to a routine that displays help then use [help] as your branch label. Or if you are branching to the end of your program you might use [endProgram] or [quit] as branch labels.

COMMENTING CODE - BASIC also has a built in documentation feature that lets you add as much commentary as you like in the language of your choice. The rem (short for remark) statement lets you type whatever you like after it (you can even misspell or type gobbledy-gook, it doesn't care!). For example:

[askForName]

rem Ask for the user's name

input "What is your name ?" ; yourName$

rem If the user didn't type anything, then ask again

if yourName$ = "" then goto [askForName]

Notice how a rem statement was added before the input statement and before the if . . . then statement to describe what they should do. Liberty BASIC just skips over these lines, but a human reader finds this kind of documentation very helpful.

Also see the way that blank lines were added between the different parts of the program? These help to group things together, making the program easier to read.

A more elegant form of the rem statement uses the ' (apostrophe, the key just to the left of the Enter key). Instead of typing rem, substitute the ' like so:

[askForName]

' Ask for the user's name

input "What is your name ?" ; yourName$

' If the user didn't type anything, then ask again

if yourName$ = "" then goto [askForName]

Most people consider this to be more readable than using rem, and it works the same way. One extra thing that you can do only with the apostrophe version of rem is to hang it off the end of whatever line you are commenting. For example:

[askForName]

input "What is your name ?" ; yourName$ ' Ask for the user's name

if yourName$ = "" then goto [askForName] ' The user didn't type anything. Ask again

This optional, but it saves screen space and many prefer it.

Learning to document the programs you write takes practice. Try to develop a consistent style. Everyone does it differently and there isn't a right or wrong way to do it. Smaller programs may not need any documentation at all. Programs that you intend to share with others should probably be thoroughly documented.

Next Section: Let's Write a Program - HILO.BAS