Somewhere in my life, apart from being editor-in-chief of CFDJ and running the Web Services Department at SYS-CON Publications, I have a bit of spare time during which I work on a few other Web sites. One of them is the official site for entertainer Michael Crawford (the original Phantom of the Opera). Recently I was called on to develop a new, secure Web board, online directory, and conferencing and messaging system for members of the site to use, along with a secure, unique logon for each of them.

My first thought was to use Allaire Forums, a great product that runs great on SYS-CON's Web site. However, it couldn't provide me with exactly what we were looking for, so I decided to take on the task of creating one myself. I started off with lots of handwritten notes on the basic logic schema of how well it would work, beginning with the registration, then processing it to allow access to the board and e-mail notifications and then to the actual workings of the board itself. I also mapped out what the structure of the database would be, including tables, queries and so on. Then it was time to start coding. After a few weeks ­ and after a few late nights of cursing and trial and error (something I'm sure almost everyone can identify with) ­ I had a basic functioning system. Next came the bug-squashing phase in which I enlisted the help of everyone I knew and even a few people I didn't till finally everything worked as it was supposed to. Then came the final phase of making it user-friendly, converting it from something designed for and by a programmer to something your average person could use.

I submitted the URL and instructions to the powers that be, who made a few minor changes ­ "little" changes from their point of view, but major changes in development from mine. After I finished whining and making the adjustments, I was done ­ the project was complete.

The system went online, and worked amazingly well. A few weeks later I got a call from a friend who was trying to set up a similar system for a project he was working on. I was very busy at the time, so I offered to send him my code, an offer he happily accepted. I sent it over to him and didn't hear back from him for about a week. When I did, the message was short: "Thanks for the code. I accept the fact that it works, I really do, but you put no comments in and I have no idea how it works. I can't use it." (There were a few expletives in there too, but those have been removed.) I dug out my pile of original notes and faxed them over to him, thinking that seeing my logic would help. It didn't. I'd only managed to confuse him even more. Finally he gave up and ­ after much more swearing at me ­ did it all himself.

I guess the moral of my little story is that no matter how great a coding job you do, without comments the code isn't of much use. To add weight to this statement, while working on this editorial I looked back at the code I'd written: large chunks of it are Greek to me too. Some of the "roundabout" logic that seemed so brilliant to me a few months ago still has me scratching my head. I am happy to report that I commented my next two projects.

I'm unhappy to report that since then I've fallen back into my old, bad habits. Time is money, folks, and the idea of cutting a corner to make something easier was just too appealing. Have a similar experience? Drop me a line at rdiamond@sys-con.com or post it on our forums at www.sys-con.com/coldfusion/.

Happy coding!