DOCUMENTING YOUR CODE THE EASY WAY!

by Alyce Watson

Home

Drawn Objects

Documenting Code

Tipcorner - Helpfile

Bmpbuttons

Prompt by Brad Moore

Locate Controls

Tips by Dennis McKinney

Demos by Bill Jennings

Review of TheWrap

Integration by Tom Nally

SQLite by Richard Peeters

Help Writing by Jerry Muelver

Index

Undocumented code is a disaster waiting to happen! You can write the best program in the world, spending much time and effort. You can be convinced that you will ALWAYS remember the logic and construction of this program. Three months later, you can open up the code to add a neat feature that just popped into your head and find that you are looking at a strange, incomprehensible jumble!

COMMENTS: THE LONG, BUT COMPREHENSIVE WAY

You can put comments in your code in two ways. At the beginning of a comment line, you can use the REM statement, like this:

REM this is just a comment and the LB compiler will ignore it.

You can also use the apostrophe/single quote to mark the beginning of a comment. This can be placed at the beginning of a line, or within a line, like this:

'this is a comment, just like the one above
print "hello"  'I can add a comment after a line of code!

NO COMMENTS!

If you don't like to take the time or the space to write actual comments, there are other ways to document your code.

DESCRIPTIVE NAMES

Use descriptive names for branch labels, subs, functions, arrays and variables. It is much easier to understand your code later or for someone else to understand your code if you do this. Which of these is easiest to understand?

MaximumNumber = 77
or
m = 77

Hmmm, there IS something to be said for brevity. It is a lot quicker to type "m" than to type "MaximumNumber" isn't it? There is a compromise. Use abbreviations! Adopt a convention of your own so that your abbreviations make sense. You might use something like this:

maxNum = 77
or 
maxN = 77
or 
intMax = 77

There can be no spaces in names of variables, arrays, functions, subs and branch labels. Make them easy to read by selectively capitalizing the beginnings of words. Which of these is easier to read:

MaximumNumber

or
maximumnumber

Avoid Liberty BASIC reserved words. Some of these will generate a syntax error when you try to compile the program. Here is an example:

print = 77

Instead, use something like this:

printCopies = 77

Liberty BASIC function names actually include the opening bracket. The name hWnd is not the full name of that function. It is hWnd(. For this reason, you can get away with using variable names like hWnd. It is best to avoid doing this, however, to avoid confusion. In the past, I've used a dot within the names of some branch labels and variables. After learning some other programming languages, I've avoided using dots in Liberty BASIC names, because dots are used in a particular way in some other languages. They are also used in LB to separate window handles from extensions given to controls, as in

statictext #win.stext, "Hello", 8, 19, 100, 26

Here are some names. Which would you understand instantly?

[openFile]
[openafileandreadintotexteditor]
[blahblah]
[wow]

a$()
person$()
address$()

Function wowthisisalongfunctionname()
Function ParseText$()

Sub dy1
Sub PlayMidi

WHITE SPACE

White space includes both blank lines and indents.

BLANK LINES

Some people take great pleasure in compressing code as much as possible. They don't want to include any blank lines, and often string short lines together by connecting them with colons, like this:

print "Hello" : x = 15 : y = 459 : print "World"

Sometimes, putting lines together can be fine, and even helpful. Setting x and y variables on the same line works fine and is short enough to read and understand:

x = 2 : y = 7

Stringing many and varied commands together is just plain confusing, as in that longer line above.

Blank lines are especially helpful to separate code routines visually. Use them in between branch labels, gosubs, functions and subs. Here are two examples. The top example requires less space, but the bottom example is much easier to understand.

''''''''''''''''''''''''''''''''''''''''''
[printIt]
open "afile.txt" for output as #f
print #f, "Hello World"
close #f:wait
[openFile]
filedialog "Open","*.*",file$
if file$="" then wait:notice "You chose ";file
wait
[quit] close #main:end
''''''''''''''''''''''''''''''''''''''''''

[printIt]
open "afile.txt" for output as #f
print #f, "Hello World"
close #f
wait

[openFile]
filedialog "Open","*.*",file$
if file$="" then wait
notice "You chose ";file
wait

[quit] 
close #main:end
'''''''''''''''''''''''''''''''''''''''''

INDENTS

Indents are the white spaces at the start of lines. You can set your own style for these. Here is the way I like to do it.

For regular code routines, I like to put the branch label, function name, or sub name all the way to the left. I then indent every other line within the routine through the END SUB, END FUNCTION or WAIT statement. The code above then looks like this:

[printIt]
    open "afile.txt" for output as #f
    print #f, "Hello World"
    close #f
    wait

[openFile]
    filedialog "Open","*.*",file$
    if file$="" then wait
    notice "You chose ";file
    wait

[quit] 
    close #main:end

That style makes it very easy to see where routines begin and end.

Indents are also extremely useful when creating nested statements. Each level of nesting gets another indent. Look at the two examples below and see which is easier to read. Note also that this style makes it easier to see where you might be missing a NEXT statement.

for i = 1 to 5
for j = 1 to 10 step 2
if i = j then
print "Equal"
end if
next
next

'''

for i = 1 to 5
    for j = 1 to 10 step 2
        if i = j then
            print "Equal"
        end if
    next
next

The use of descriptive naming, along with the judicious use of white space, makes self-documenting code. There will still be spots that need some additional documentation in the form of comments, but reading and understanding the code will be much easier with these techniques!

Home

Drawn Objects

Documenting Code

Tipcorner - Helpfile

Bmpbuttons

Prompt by Brad Moore

Locate Controls

Tips by Dennis McKinney

Demos by Bill Jennings

Review of TheWrap

Integration by Tom Nally

SQLite by Richard Peeters

Help Writing by Jerry Muelver

Index