Programming with Comments

I seem to be addicted to mailing lists.

I used to (back when I was in college, so it is getting to be a while now) read USENET a lot. It quickly became apparent that each newsgroup only had two or three topics, and that they cycled through them on approximately a two-month period. But that is alright. There are so many different groups that there is always something new to read.

I rarely ever post, though.

I can't do anything more than speculate as to why this is true, but nearly any thread that I posted to died instantly. [For the non-USENET savvy, a thread is a series of posts, usually between 2-5 people where they "reply" to each other's posts by ignoring whatever was said and restating their own opinions.] I've tried tones ranging from friendly, through concecending, to downright hostile. Always the same. Dead. Even when I ask questions in groups that seem to be good about answering questions. Usually it is as if I never even posted. Dead.

So I rarely ever post.

Because that makes my reading material stop.

So one of the mailing lists I subscribe to is dedidcated to discussions around the Squeak Smalltalk language. And recently they had a discussion about class comments. The jist of the conversation centered around what was a reasonable minimum amount of documentation to require in a program. Some people were of the "if the code requires comments, it is poorly written and should be refactored until it is readable." While I think it is good to put some effort into making the program by itself readable, I have written a pretty substantial amount of code that no amount of refactoring would ever make understandable without some basic comments. A couple people wanted a comment on everything, but that's just as clearly overkill. A sort of reasonable comprimise seems to be to only really require writing one comment for each class of object in the program. That's probably more reasonable, but to me still seems wrong.

Knuth wrote the Web book some years ago, but somehow it's never really caught on. Funny. When I read it back while I was in college, it seemed like such a good idea. The downside was that it was so painfully mechanical. Everything about it just seemed to hurt when I tried to do it.

Squeak Smalltalk has this interesting property where not only is the code and the data all mixed up and interchangable, the program being built is mixed up with the environment it's built in and even mixed up with the tools being used to build it. The resulting slurry can be confusing to the outsider, but once you develop the taste for it, it goes down smooth.

So now I wonder, maybe if there is a way to build a hypertext document in Squeak objects which describes an object class. It could have pictures, sounds, animations, whatever helped to tell the story. But part of the story would be the actual code that would control the behavior. Just like Knuth's Web, the idea is to make the description be the program, and put just enough extra tidbits into it so that the computer could actually execute it.

Too bad I'm to lazy to ever try building it.