------------------------------------------------------
The Laws of Coding, wherein some good ideas are listed
------------------------------------------------------
The Laws of Coding are as many and dimensioned as there
people who code. Here is contained many real laws, of
both positive and negative nature.
Some comments regarding the discovery of these laws and
further expounding on their meaning is found after the
list of laws.
An attempt has been made to list contributors of laws or
commentary. This can be found at the end of this document.
The order and numbering of laws is due to the whimsy of
the editor, and has little bearing on the importance or
precedence of the laws, other than that an attempt has
been made to segregate positive and negative laws (those
of the HHOS nature, as defined in TNHD); and that the editor
feels that thinking is very important to coding, and thus
should have the central position.
------------------
The Laws of Coding
------------------
Rule -4: Yeah, but REALLY good programmers can read MY code.
Rule -1: Remove all Syntax Errors before releasing.
Corollary: If it compiles, ship it.
Or to put it another way, "Quality is Job 1.01."
Rule 0: Think before you code.
Rule 1: If you write the same code in more than two different places,
you are doing something wrong.
Rule 2: Programmers should strive for invisibility.
Corollary: If you think something is "cool", it's probably going to
annoy the user.
Rule 3: Programmers design Programs; Users should design User Interfaces.
Corollary: Graphic Designers should design Graphics.
Rule 4: Good programmers write readable code.
--------------------------------------
Commentary by various persons, edited.
--------------------------------------
Comments by Anthony Berno:
(on rules 1 and 2)
I haven't been programming for all _that_ long, and have only been doing
full-fledged applications for about four years. In this time, I have
encountered some principles that seem obvious, yet which are often
overlooked. Being somewhat arrogant, I would like to propose two rules of
application programming, Rule 0 and Rule 1, with the idea that others may
add to the list.
[Rule 1]: If you write the same code in more than two different places,
you are doing something wrong.
->I consider this fundamental enough to merit status as the zeroth rule.
My experience has been that it is almost always true, and breaking the
rule leads to maintenance nightmares. No matter what the situation, there
is *always* a different technique, a different viewpoint, or a different
language that will fix the problem of code duplication. Seems obvious, I'm
sure, but it needs to be codified - I've even seen it violated by
"professional" programmers.
[Rule 2]: Programmers should strive for invisibility.
Corollary: If you think something is "cool", it's probably going to annoy
the user.
->Programmers that draw attention to themselves with flashy screens,
clever tricks, or "cool" features are being self indulgent at the expense
of users. The best software is that which renders itself nearly invisible
to the user; the user simply does what (s)he wants without even noticing
the mechanism behind it.
The worst violation I have seen of this was in an undergrad graphics
class. The assignment was line clipping; our program had to allow the user
to specify a rectangle on the screen with a mouse, draw 500 random line
segments, and clip them to the rectangle using the Liang-Barsky algorithm.
Simple, right? Just bring up a window, and use a standard click-and-drag
to draw a rectangle. A single line of explanation, and an inconspicuous
"quit" button, are all that one might need to add.
The executable versions went into a publically-readable directory, so I
took a look at some other solutions once I was done. My favorite had a
DOS-style menu structure. The menus I navigated through went something
like this:
1: Run program
2: Quit
(Choose 1, and then...)
1:Specify first corner
2:Specify second corner
3:Draw lines
4:Go back
(Then, when you choose 1 or 2...)
Click mouse in window. Press return when done.
This was pretty outrageous, I know, but there are lots of other programs
that are written in the same spirit. Some Windows programs are particularly
bad this way. And I'll bet the programmers think they're being soo cool...
On the other hand, many programmers have done a pretty good job. It's not
until you write apps yourself that you realize just *how much* a good
graphical application does without making itself conspicuous... and how
thankless and self-effacing a job it is to write good applications!
So there's my 10 cents. Anyone have any rules of their own?
-Anthony
Comments by
either Elizabeth Haley
or David Charles Todd:
(on rule 3)
Programmers design Programs; Users should design User Interfaces.
Having talked to numerous people in various office settings, The
cardinal sin I have seen being committed is that programmers design
the User interface for a program without ever asking those who will
actually have to *use* it how they do their job... The best I have
heard of is the programmer talking to the office manager... But often
times, the office manager doesn't actually have to use the thing all
day, just once in a while.
One book I read on office automating suggested that a 6 month study of
office procedures was needed before design could begin. Your mileage
may vary.
Jonathan M Lennox adds:
(on the corollary)
What's more, Graphic Designers should design Graphics.
How many times have you seen (if you're the kind of person who
deigns to use a GUI) some software off the Net or from a small company
which has some utterly incomprehensible icon and a badly-laid-out
or ugly interface...just because programmers can work wonders behind
the front end, doesn't mean they necessarily have any aesthetic
sense...though too many of them think they do.
Comments from Edmund Blackadder:
(on rule 4)
The user's setup will NOT be identical to yours.
Too many programs assume that the target machine's hardware setup and
filesystem will be exactly the same as that of the programmer. Some examples
of this in the Intel x86 world:
- assuming that the installation will be from drive A:
(if your disks are the wrong sizes, you have to switch cables.
Some install programs make no provisions for installing from B:)
- you have the proper .DLL files already (for OS/2 or MSWIN programs)
(if they're not in the archive, you have to hunt FTP sites)
- mouse and modem are on COM1 and COM2, respectively
- the program is stored in C:\{PROGNAME}
(we have one application on the network I run that has hard-coded
pathnames for its support files and therefore must be in the
directory C:\CROWD. So, to run it, we have a batch file that will
copy the entire directory structure from the server onto the local
drive, and then erase it when finished. Many games have this
problem also, and those of who prefer a clean root directory and
deep hierarchical structure have to tweak the installation...)
- Similarly, there are absolute pathnames for support files
(I've seen code that requires graphics drivers (Borland *.BGI
files) to be in C:\TPASCAL\BGI.)
- conflicts with another company's software are Not Our Problem
(Microsoft seems to be a major offender in this area. Win 3.1
did not work with DR-DOS, and I've heard that NT cannot
coexist with the OS/2 boot manager, which means you can't have
multiple OS's on one system. )
- all files are writable
(fails on a network drive or multiuser OS. Some programs will
attempt to update their configuration, and either hang or
continue without an error message)
Comments by Lars R{der Clausen:
[Rule 0]: Think Before You Code!
I've seen this broken so many times, with not only bad, but usually disastrous
results. I've also done it myself sometimes, and the code was invariably
unreadable a few weeks later. On the other hand, the few times I've seen
things really thought out, they were beauties. I'd say a proper programming
recipe would be 1/3 thought, then 1/3 programming, then 1/3 debugging. Though
that's probably giving too much time for programming...
------------
Contributors
------------
Anthony Berno
[email protected]
Michael A. Gelman
[email protected]
jim frost
[email protected]
either Elizabeth Haley
[email protected]
or David Charles Todd
[email protected]
Edmund Blackadder [Yeah Right. -ED]
[email protected]
Mark 'Mark' Sachs
[email protected]
Jonathan M Lennox
[email protected]
Lars R{der Clausen
[email protected]
Billy Chambless
[email protected]
Charles Perkins (the editor)
--
.8Chuck .2Socrates
[email protected]
[email protected]
"I drank what?" "Pepsi." "Oh."
