23 May, 2007

Theme tinker

Yup. Decided green was no longer the in thing, so I ditched it in favour of another of the pre-canned themes available from Blogger. Had to tweak a little until I got what I wanted, i.e. a bit of mix and match - some of this theme, some of that theme... it's not ALL working out, but I seem to be working through the bad bits slowly. Anyhow, lets get this theme to bed so I can get to bed myself... I'll write a bit more tomorrow if I think of it. The last thing I want to do is to replace the background colour with something a little more exciting. Like a New York cityscape. And hey, why don't I lighten up the background display over all?

From the Weekly Squeak: What's in a Comment?

Today, I saw a news article with the following title: What's in a Comment? « The Weekly Squeak provides yet another look at why we should comment our code, this time from the perspective of a SmallTalk developer. You can read the rest of the details at the link above, but that's not where the story ends. Frankly the comments make more interesting reading than even the article does, though the article is entertaining enough. An excerpt from the article best describes this:
I believe that these statements, the code is self documenting, and there is no good place to document in code, are wrong. Comments deliver two very basic benefits. First they give context to flow. Good comments can help to point you in the right direction. If you have a method that is protected by callers or has other considerations that may limit the usefulness of a method, you had better put a comment in. Otherwise you can be sure some other developer will use the method wrong and make the mistake you thought was obvious. Class comments are a very good example of this. Having a class comment that just points you to the default flow of the object can really help.
I wholeheartedly agree with this, and don't think the standard excuses of "not enough time" hold up. I do accept that when a professional codes, that there IS a time constraint. After all, the programmer is often paid by the hour, and spending an extra two minutes per hour doing the documentation when the job is already clocking up the time doesn't seem worth it when you consider that the typical market for the code is non-technical users who will never look at the source code. But there are two things I believe worthy of consideration here. First, the documentation and comments in the code aren't for the user, they're for the coder. The second point to consider is this: the extra two minutes pays off in rewrites—when the next coder comes along to maintain the work, good comments and strong (that is, correct and relatively complete) documentation will mean that she can often do her job in half the time it would normally have taken her. Now, that's a lot of dosh saved.