The non-programmers of you can sit this one out. Don't panic, the funny stuff will be back later.

This is a little list for all of you out there who think that you're professional programmers.

You're wrong.

You're not professional programmers, because you don't document your programs. If you don't document your programs you're an amateur at best, and at worst, you're a con-man, because you're selling something without the instruction booklet. Documentation is what separates the professionals from the amateurs and con-men, and, judging by a lot of stuff I've seen on the web, there are very few programmers who can really call themselves professional, and an awful lot who should be banged up in jail.

So, if you want to be a professional, here are the rules that you better start using:

Why You Must Document

* Rule1 *

"LOOK AT THE CODE" is not an acceptable documentation standard.

This is like telling someone to learn how to drive by looking at a car engine.

You should document your interfaces so that another programmer can understand the function, and what to send and receive without having to look at the code. Pulling your code apart to learn how it works is a waste of my time and yours.

If you want people to use your code, you must make it easy for them to use it. Nothing makes code harder to use than it being undocumented.

Anyone who uses this phrase should seriously consider changing careers - possibly to selling dodgy life insurance, as that's more your line.

* Rule 2 *

Automated documentation systems should be a last resort, not a first one. Automated documentation systems are, at best, lists of methods, with very little explanation. Such programs are nothing more than excuses for not doing documentation. A plain-english explanation of how things work is far better.

If you can't explain it in plain english, no amount of clever extraction programs are going to help you.

* Rule 3 *

Your code is worth NOTHING unless it is documented. In fact, it is worth worse than nothing. If it is not documented, your code is a liability, not an asset.

* Rule 4 *

IN THREE MONTHS TIME, NO-ONE WILL UNDERSTAND AN UNDOCUMENTED PIECE OF CODE, INCLUDING THE AUTHOR.

To sum up. Undocumented code is a liability. Undocumented code slows the learning-curve of new programmers. Undocumented code causes significant drains on resources, because a programmer has to re-learn how to use it. Undocumented code causes unnecessary work, through both duplication of function (because no-one has documented the function correctly), through reverse-engineering, and through avoidable errors.

SO, LEARN TO DOCUMENT.

Today's post has been brought to you by twenty years of stored-up rage.