------------------------------------------------------
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
aberno@godel.questor.wimsey.bc.ca

Michael A. Gelman
mgelman@orleans.ma30.bull.com

jim frost
jimf@centerline.com

either Elizabeth Haley
       haley@scws7.harvard.edu
or     David Charles Todd
       hacksaw@headcheese.daa.uc.edu

Edmund Blackadder [Yeah Right. -ED]
hucke@ux1.cso.uiuc.edu

Mark 'Mark' Sachs
MBS110@psuvm.psu.edu

Jonathan M Lennox
jml12@cunixa.cc.columbia.edu

Lars R{der Clausen
elascurn@daimi.aau.dk

Billy Chambless
chambles@whale.st.usm.edu 

Charles Perkins (the editor)
-- 
 .8Chuck .2Socrates
 perkins@admn1.law.utah.edu
 caperkin@ursa11.law.utah.edu
 "I drank what?" "Pepsi." "Oh."

