Frustrations, theater etc..

Between rehearsing for the new play I'm in, work and the usual madness of everyday life I've not really had an opportunity to compose anything of note for this space.

That said, I do have a large article (and I mean embarrassingly large article) which goes into how to document code in an effective way. I wrote it because I kept having deja-vu when it came to code comments. The things I wanted to know weren't there and what was commented was completely obvious. I was also getting the vibe from many on the team that code commenting was completely pointless, which was quite obviously bogus since Sun has managed to provide some very decent java doc comments for their code. What I have done is kept track of which things I want to know when I approach new code and put them all into a large document in a check-list sort of form.

The document became rather large when I realized that many of the items in the list only really made sense if you knew how to write good code. As a result I needed to explain how to write the piece of code in a format that doesn't require code comments before getting into what to comment. In fact, many of the items in the list can be thought of as warnings of the form: "Watch out! This code is not written how you think!".

In the end the guide is as much about how to code well as it is about how to document well. It's quite a nice read.

Anyways, that will be coming up as soon as I can figure out how to translate the behemoth into blog form.

Ok, gotta get back to learning my lines. See ya.