Peter's site  

www.MadmanPierre.com

The Laws of Programming

1. If it's a stupid design but it works, it isn't stupid. 
2. No code ever survives its first draft. 
3. There is no such thing as perfect code, unless you are talking about "my" code in the common library. 
4. Important things are simple; and simple things are always hard. 
5. Anything you program can go wrong, including nothing. 
6. For every programming style, there is an equal and opposite criticism. 
7. When reviewing the code snippets that you wrote down on a scrap piece of paper out of the office, the most important ones are always illegible. 
8. Stealing code is called plagiarism. Stealing code from a smarter Programmer is called innovative and smart. 
9. There is always a way to code something, and it usually doesn't work. 
10. If only one solution can be found for a coding problem, then it is usually a stupid solution. (See rule #1)
11. Any given program, when running, is obsolete. 
12. If a program is useful, it will have to be changed. 
13. If a program is useless, it will have to be documented. 
14. Program complexity grows until it exceeds the capabilities of the programmers who must maintain it. 
15. Adding manpower to a late software project makes it later. 
16. The only truly original algorithms were by a time traveler who stole them from the future. 
17. The better the program, the more it will make the user want a better program.

Failure:

FAILURE IS NOT AN OPTION! It comes bundled with every copy of our software.

Help Files:

Most computer "help files" should be called "unhelp files"

If all else fails, stop reading the manual, you'll do much better that way.

Serious (yet, tragically funny) comments:

A user was lamenting that a software manual was so riddled with errors that it was easier to use the software by ignoring the manual. She also explained that whoever wrote the manual didn't think about how the software would be used, just how it was written. I explained to her that unfortunately, this is the normal case for computer manuals. I wish it weren't a joke, but it is true that Manuals typically document:

1. The way the software was supposed to work OR

2. The way someone who tried the software once THOUGHT it worked OR

3. Someone goes through each screen, documenting each field with useful comments like "The Title field is the location at which you should enter the Title that you want to use. The size field is the location at which you should enter the Size that you want to use. The ...." Well you get the idea.

In the fall of 2002 an Alberta Government software package sent to schools throughout the province came with a document

- grandiously titled "[name of software] Manual". (Yes, the words "name of software" were the actual words on the manual.)

- Inside was 1 piece of paper that listed the hardware required to run the computer! Nothing about the purpose, loading, installing or using of the software!

- And worse ... it turns out that this list of required hardware wasn't even correct!

Not a joke. Creating real manuals:

Note: I have been involved in creating "real" manuals, books and articles for "real" software. I understand that most developers, having spent way too much time and effort on the development just can't be bothered writing good manuals. In my opinion, the number 1 missing feature of most manuals is a "procedures" section. This is a section that stands back and asks:

- What are all the objectives the user will want to accomplish with this software.

- What are all the typical work flows.

- What are all the unusual (but legitimate) work flows.

- What problems might the user encounter and how should they go about solving them.

Once the software gets into alpha and beta test, every question asked by the testers should be considered in light of the above 3 questions to see if it warrants documentation this way.

The number 2 feature missing in most manuals is a USEFUL index. Most software packages will have manuals that only document using the words used by the software developers. For example, in a product that has "Automobile", so the index has an entry for automobile. But it should also have index entries for things like car and vehicle as appropriate to the software. Just because the developer used the word "Automobile" doesn't mean that the user will immediately think of looking up under automobile. Remember: If you don't immediately come up with the words your users will search by - they won't come up with your words when searching the index.

So how do you gather good words for an index? This is easy! I'm glad you asked! You initially provide the manual on line only, with a search engine for finding words. You then record every word searched on, whether the word was found or not, and ask the user to reply whether the search resulted in the expected information (with a comment field for them to explain). Then you study the results, especially the "no hits" and the "well, it found the word, but that wasn't what I was looking for"s.

Also, all error messages should be documented in an alphabetic way (or indexed) and then key it to the procedures section.

Other Short and One Liners

Computer programming often has cryptic codes that make sense only to the developer. One day I was working through some code where all variables of a type started with "T" followed by a word or phrase. In the code review we came across TReason, upon which one of the reviewers cried out "That's TREASON!"