Liberty Basic is develeopped by Carl Gundel
Original Newsletter compiled by Alyce Watson and Brosco
Translation to HTML: Raymond Roumeas

Brosco's Liberty Basic Resource Centre Newsletter - Issue #4 - May 1998

 
 

In this issue:

  1. Towards writing more readable code - Part 1
  2. A short story by Brosco


1) Towards writing more readable code - Part 1

After 30 years of writing programs - I still make typos, I still misspell variable names, and I still can't understand code from a program that I wrote a few weeks ago. Understanding someone else's code and trying to Debug it is like reading a foreign language!

Quite often, a professional programmer spends his first year or two as a trainee - and the only work you do is to perform maintenance on other people's programs. Maintenance programming involves two things:

1) Fixing bugs that have only just come to light

2) Modifying the program because of business/environment changes - such as:

Inceasing the size of ZipCode to allow for Government changes

Allowing for a new form of sales tax

etc

Fortunately, programming standards today have improved dramatically from the days when I first started. I remember one program that I had to modify where the programmer used Variable names and [Labels] based on his favourite TV shows. So there where names like [RinTinTin], [Flipper], [Skippy], etc.

The program made quite amusing reading:

if PeytonPlace - Mash = GeneralHospital then gosub [DaysOfOurLives]

But it didn't help me to understand what the program was doing. In fact, several of us tried to understand the program so that the changes could be made. We all failed. The program had to be completely rewritten to incorporate the changes. This obviously took far longer, and was an unneccessary expense to the company.

In a professional enviroment today, programs like that would not be allowed to be written, but at home, there are no controls in place to stop you from doing so.

Even if the program that you are writing is purely for your own use, plus you have no intention of posting it for others to understand, you still owe it to yourself to make it easy for you to modify if some circumstances change that require you to upgrade your program.

One of the first things that people tell you to do to make programs more readable is to add plenty of comments. This probably helps, but if you look at my programs, you will see very few comments. First off, its because I'm lazy, but secondly, I have other techniques that work well for me. The following rules are not official or endorsed by any standards committee - they are just the rules that I have created for myself.

***** Rule Number 1.

Be consistant with variable names.

For example, we all write programs that read a file. Typically the variable name that people use for the 'file name' is File$, filename$, FileName$, File.Name$, etc. and they are all fine - but select the name that you like, AND STICK TO IT! This will make debugging far easier - because you will cut down on the number of ways that you 'spell' filename$ when you use it.

***** Rule Number 2.

Try not to make lines of code longer than something that fits into the display width of your editor's window. While debugging, scrolling left and right across a line of code makes it very easy to lose concentration on what the code is actually doing. Matching up left and right brackets becomes almost inpossible. Use the continuation command (see Newsletter #3) to make the line display over multiple lines.

***** Rule Number 3.

Make logical functions fit within one Display screen. This is similar to Rule #2. If you need to scroll up and down to see the the start and end of a For...Next loop, you will get yourself confused very easily. Simply pull out parts of the code and turn it into a GOSUB.

***** Rule Number 4

Use plenty of 'White Space'.

'White Space' is what people call putting in blank lines. Its a great way of splitting up the functions in your program. For example:

[Save.File.Click]
    FileDialog "Save File", "*.txt", Filename$
    if Filename$ = "" the goto [loop]
 
    Files left$(Filename$,3), right$(Filename$, len(Filename$)-3, info$(
    if val(info$(0, 0) > 0 then
        Notice Confirm "File exists! Overwrite?"; answer$
        if answer$ = "no" then goto [Save.File.Click]
        end if
 
    open Filename$ for output as #f
    .....
    .....

Notice the two blank lines (white space). First I try to get a filename and after I am sure that its retrieved, I leave a blank line. The next section of code is to handle the filename. I check to see it the file exists, and make a decision on what to do - and then leave another blank line.

Finally, I come to the part that outputs the file. Those two blank lines make this section of code dramatically easier to read simply by splitting the logical functions within the process.

***** Rule Number 5.

Indent your code.

I put [Labels] in column 1 of the text, program statements at one TAB (in LB thats 4 spaces) in. Then, when I use a FOR..NEXT, WHILE...WEND, IF...END IF, etc. I indent that code with a further TAB. I allow myself one further indent if I use another FOR...NEXT, WHEN...WHILE, etc., but after that, I would split the process into GOSUBs so that my code didn't disappear off the right of the display.

If you follow these five simple rules, you will find that your code will become much more readable, easier to debug and look far more professional. In future newsletters I will discuss further techniques, but in the meantime, just try to get used to these few simple concepts - I promise that if you follow these techniques, in the future, you will thank me for them.


2) The lonely programmer.

A very short story by Brosco.

Its after 3am, the eyes are bloodshot, the head's spinning, the ashtray is overflowing - another cup of coffee is just not going to help anymore, when EUREKA!!!!!! that bug thats been eluding me for hours is solved!!!

The new masterpiece is finished - WOW, what a sense of accomplishment, what a feeling. I just have to tell someone! ANYONE! Wake the spouse, errrr, better not. I know, I'll post it on the message board - everyone will be so excited when they hear about this. In fact, there's probably someone in some part of the world on the net RIGHT NOW! I'll sit back and wait a few minutes - I'm too excited to sleep anyway.

Geeez, where's that timezone converter - someone must be awake somewhere - oh well - I'll check tomorrow before I go to work. I bet there will be a 100 emails waiting for me.

Ah yes, "Downloading 1 of 19" - yep, the guys have been active, " ... 7 of 19" - bet they are dying to get their hands on this!!!! "... 19 of 19" - Ok - all done - lets see what they have to say.

Ahh - first message - some guy wants to know about Release 57.45 of Liberty Basic. Next ... something about the InfraRed API to contol the VCR .... Here's one about controlling the 4th parrallel processor using 128 bit calls .... boring stuff .... geeeez - didn't anyone read MY posting?????

Sigh - I guess I better keep my day job.

******************************

(And I know - I'll stick to writing programs in future)


Newsletter written by: Brosco.
Comments, requests or corrections to: brosco@orac.net.au
Translated from Australian to English by an American:
Alyce Watson.  Thanks Alyce.