Consider the following block of code:
while item$<>"end":x=x+1:read item$:item$(x) = item$:wend:item$(x)="" [go] changed=0:for x=0 to x-1 if item$(x)>item$(x+1) then oldLine1$=item$(x):item$(x)=item$(x+1):item$(x+1)=oldLine1$:changed=1 next if changed then goto [go] for i=0 to x:print item$(i);:next:wait data "Chunk of ","zation","Evaluate " data "For Al","Data to ","phebeti","A ","end"
Sure, that code will work, but without
running it, you may be asking yourself, "What in the world does
it DO?"
In fact, you may be asking
yourself the same thing even if you wrote the code in the first
place!
I'm only 32 years old, and considering the state of my
memory today, I fear what the future may have in store. This is
especially true where my programming code is concerned.
So
what do we do about code that only a computer could understand?
How
do we remember what we were doing years after we did it?
How do
we let other people know what we were up to so they will stop
bothering us about fixing our years-old code?
Adding
comments to your code is easy! To find out how to do it, send a check
or money order to....
Sorry. Forgot what I was doing there,
for a moment.
To add comments, simply put in an apostrophe. It's
that easy. Everything you write after the apostrophe will be ignored
by the compiler.
Now you may be asking, "What do
comments have to do with anything? If the computer could understand
the comments I make about it, it would never speak to me again!"
Actually, comments should not be directed at the computer but
rather, to the programmer. They make it much easier for people,
possibly thousands of years from now, to understand what you were
trying to accomplish, and maybe give them a good laugh or two, when
they see the difference between what you were trying, and what you
ended up with. (I've heard that Microsoft had to remove comments from
a lot of its old code because their programmers never got any work
done, with all the snickering, giggling, and outright knee-slapping.)
Another thing that helps improve readability is "White
space".
See how the code above is all scrunched together?
You're not paying for space, here, and the compiler will arrange it
how it wants when it comes time to build your program, anyway, so why
not make things easier on yourself?
Spread out. Relax. Get
comfortable. Take your shoes off.
Sniff, sniff...
On
second thought, leave them on.
Adding a blank line or two
between related blocks of code helps separate various routines, and
gives the eye a break once in a while. (Considering the strain you're
asking of it, trying to decode your heiroglyphics, it needs all the
rest it can get.)
In addition to blank lines, it is helpful
to indent lines of related code. For example, when you have IF...THEN
statements, it helps to set apart the code that will execute only if
your condition is met, if you indent the lines of your conditional
statement between the IF and END IF statements.
This is called
"Nesting."
Now let us consider the code from above,
arranged into some form of coherent order, and with some commentary,
white space, and nesting added.
' A simple program to sort items into alphabetical order WHILE item$ <> "end" ' Look for end of data marker index = index + 1 ' Increment the item counter variable read item$ ' Read the data that will be alphabetized item$(index) = item$ ' Put the data into an array WEND item$(index) = "" ' Remove the "end" marker from the end of the array [go] changed = 0 ' Establish/reset a flag, so the program will repeat sorting until nothing has changed. FOR index2 = 0 TO index - 1 ' Use a second index marker and run it up to one less than the number of elements in the array IF item$(index2) > item$(index2 + 1) THEN ' Compare the items, and if the first is higher than the second, swap the items oldLine1$ = item$(index2) ' Put the first item into a temporary variable item$(index2) = item$(index2 + 1) ' Put the second item into the first item's slot item$(index2 + 1) = oldLine1$ ' Finally, put the first item into the second item's spot. Exchange accomplished! changed = 1 ' Set the flag to repeat the procedure. END IF NEXT IF changed THEN GOTO [go] ' Repeat if anything has changed FOR index = 0 TO index2 ' Now print all of the items on the screen PRINT item$(index); NEXT END 'End of the program DATA "Chunk of ","Evaluate ","A ","Data to " ' This section has all of the data to be read into the array DATA "For Al","zation","phebeti","end" ' The end marker goes (surprise!) at the end!
Eureka!
Now we see from the
very beginning that this is a sort routine. So, now we can close it
and go looking for the game we were trying to find, all without
losing valuable playing time.
The white space spreads things
out so we can easily see the individual parts of the code, and the
comments tell us what it is doing at any given time.
You
don't have to wait until you're done coding to write your comments.
In fact, I usually write nothing but comments until I have described
all of my program and what I want it to do, then go back and write
all of the computerese code around the english description of the
program.
As time goes by, and you develop your own coding
style, your use of comments and space becomes automatic. Developing
good commenting and stylistic skills while you are still learning the
basics is good practice.
It is not "wrong" to produce
"ugly" code, such as the first example, at the top, but it
does make it much more difficult to support the code, when there is
some question about its functionality. The computer doesn't care what
it looks like. It only does exactly as it is told, and has
no sense of style at all.
So it's all up to
you.
Computer geeks in charge of style.
Heaven help us all.