Amiga Computing - Commodore Is Awesome

vs
I)
• • 0
• • • •
• • •
• • 111 •
his months theme, in a nutsnell, is
about writing understandable code,
and while most programmers will
doubtless have their own ideas on
what constitutes an easy-to-read program, I
thought it might be useful to recap on the
Conventions I use. One thing that is obviously
helpful is the use of understandable names for
variables and I tend to use lowercase names.
adding underscore characters to improve
readability.
For example, an Mexx statement which reads:
iii t_f ligT
f. se t nit fle e - didif
lUE .1
/, has decided to dolt *I
!s
s
I
n
With m function names I capitalise the first letter of
each y part of the function name -
CalculateAverageo, m
GetResponsen and so on.
ARexx i itself doesn't care about the capitalisation
(function n names are all treated as upper case
anyway) d but the above mentioned arrangement
does , seem to aid readabefity.
m Above all make sure the name tells you
something u about what the function does -;t
may c seem all very clever at the time to create a
function h called HaveANiceDay() but six months
later p its likely to be you who's sitting there
wondering r what on earth It does!
e ARexx variables are effectively typeless so
you f don't need to declare variables as hokdino
enumbers,
strings and so on Despite this,
rbelieve
it is actually very useful to be able to
r
imply something about the type of data held in
ea
variable from its name.
d
You may have noticed that I often add a S
t
Suffix to Men variables which are specifically
o
used to hold text smngs. I might, for example
suse
nameS and address$ to collect name and
o
address strings from a user. If. on the other
m
hand. I knew that the user input was going to
e
be a number then id use variable names like
t
value, age, x, or n.
h
should point out that in this case these
i
'pseudo type' arrangements are not a common
n
ARexx convention and internally. ARexx cares
g
little about the types of values placed into a
l
variable. Nevertheless the convention has
i
Served me well and it is one I recommend.
k
e
With some advanced applications it is also
: occasionally useful to adopt additional
conventions. Prefixing global variables with the
character g_ and suffixing pointer variables
I1a5511 wding• •••• Il • •••
lte115
•••
•••
i[H
1
Praire.. 1
1
•:
-J1
ite rkbe nch
-
1
,
1
dmi ;She ti
* spy
his micro w
t
▪ Fine tC e 1 1 0
sut s
lions •e sotts
H •
•d :C ld:t. tc4
s t t
* /
Set pe rsm•te rs to be to rotor units. .0 .
' tit 0o
Outer
simply by loading values into vanables [which
are subsequently never changed[ My
preference is to use uppercase names for
constant values like this.
ESCAPE • 'WA
By getting into the habit of placing such
Fair comment
All Mem( programs have to start with a comment line so there's a good chance there
will, at least, be a program name at the start of your scripts. But why stop there -
additional comments can make a world of difference to understanding a program.
Don't make the mistake. inCidentally, of thinking that comments are just for the
benefit of other users and that you understand your code well enough not to need
additional remarks. You may understand your code when you write it. but it
amazing how code tricks, which seemed perfectly obvious at the time they were
written, appear to loose their 'inherent obviousness' as time goes on.
You should not get carried away to the point where you impose unreasonable
numbers of restrictions on either yourself or anyone else who has to read your code.
The aim is to adopt a set of coding guidelines which help and are easily usable, and
luckily, for the most part at least, all that s needed is common-sense coupled to a
consistent methodical approach!
Copy Je st
T
O
N
.
▪ ftine
lt 1 1
1 1
t • C a C
i
s g::1 :
h
e•
a /
d
• Oft the So
4. I t thpfe •F
/4.
"
•.4 t .rne .141
-
,
b
r
pleti
o " - • a/NOV
a
'
r t
e
.
0/
A hills extra Cara g when wrelona Allema script*
can produce clividanda ) In the ions run!
:
t
Using _p can help tell e you something about the definitions near the start of a program. you will
data stored in the variable. l
t
Another rule of thumb' i concerns avoiding
always know where to look for them the
separation also makes the values easy to change
the use of absolute Constants n within the bulk of and because symbolic names rather than the
your program code unfortunately. ARexx
underlying definitions themselves are used, the
doesn t provide much direct help in this area program automatically becomes easier to
but 'pseudo constant' values can still be set up understand.
This 'trick' is especially useful when dealing
with control character sequences (this of course
was what last months instalment was all about'
but the ideas can also be applied in other areas
as well. There is. for instance. a good case,
particularly with larger scripts, for eliminating
explicit text messages from the bulk of your
code. If. for example, you Set up this initial error
message definition
Indium/ . 'sorry this •ILUS is not
correct'
then within the main sections of the program
the appropnate error message can be displayed
using:
say WRONG_ViLin
Equally important is trie fact mat the message.
which may actually get used in a number of
different code areas of the script, is now defined
in a single place This ensures that any changes
Co the initial definition results in those
modifications automatically being used
throughout the program!
Amiga Computing
MAY 1995
•••• •
If qou haue
trouble
understanding
Ahem (Ode
qou'ue written
months or
gears ago,
the5e guide
lines from
Paul OLIPrad
(fluid make
tour coding
life ea5ier