------------------------------------------------------ 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."