---------------------------------------------------------------------------
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
                    *************************

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. 

            ****************************************************
                             
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 mailto:brosco@orac.net.au

 Translated from Australian to English by an American:
 Alyce Watson -  Chief Editor.  Thanks Alyce.

 
  
 




