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!
If you don't like to take the time or the space to write actual comments, there are other ways to document your code.
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 includes both blank lines and indents.
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 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!