Commenting Code

There’s an interesting thread on SlashDot about when and how to comment code.

Lots of programmers seem to think that comments are a waste of time, but when I interview a programmer I always ask about how and when the programmer comments. I’ve been known to ask a programmer to walk through commented code, explaining what it does. If you really know what you’re doing, and your code, you should be able to explain it to someone who knows the basic concepts of programming and understands the task at hand.

I think comments are important, not only for future maintainers, but as a help to the coder who writes them. You will forget what you meant a particularly brilliant bit of code to do when you come back to it six months later, or even the next morning after an all nighter. Comments will help you remember. Make them descriptive, and specific, and you’ll find that thinking about what the code does will often help you stream line as you discover flaws in your “narrative strategy.”

Yeah, I know, code doesn’t have a narrative strategy, but are you sure? Think about it. There’s an order in which steps must happen, a process, with a defined beginning, middle and end. Use comments to gloss the process. User short descriptive variable names, not, please, Polish variable names, as one programmer I worked with did, unless of course, you’re coding in Poland. I’m not a programmer, but I’ve looked at a lot of code, and worked in a few scripting languages. I usually write some comments first, outlining the basic parts of the routine, to help me organize my thoughts. I learned that from the person who taught me to use my first scripting language, and it does help.

Apple’s OS X Address Book

Dave Winer writes regarding the “Jaguar” release of the Mac OS X address book:

There’s some concern that Apple is not allowing the chat client vendors to access the system address book. If so, this is a repeat of the Sidhu mistake. It will end badly for the developers, but it will also end badly for Apple.

I think there’s no need to worry and that Apple wants to provide access to the revised Address Book. I notice that at the just-concluded WWDC apple had a session on Friday May 10 at 2:30 on the “Address Book Framework.” The description of the session reads:

012 – Address Book Framework
This session provides an overview of the Mac OS X Address Book APIs and details how to take advantage of them to handle contacts for your application. Learn how to leverage this framework within your application to save substantial development effort and time and deliver a more consistent user experience across Mac OS X.

That sounds to me like there are just the sorts of APIs that Dave is talking about.

Blackboard coaxing WebCT users to Defect

In this press release BlackBoard urges WebCT users to come to the mother ship with promises of “conversion kits.”

You know they aren’t doing this out of the goodness of their hearts, which makes me wonder just what kind of “conversion” and support they are offering. I’m not going to speculate about why and what a user would be converting. After all, both companies purport to use open standards right down to their meta data. It’s also likely that that the sites to be converted are would need to be fairly vanilla, that is, template driven, “course module” using sites, rather than anything more instructonally appropriate or useful.

The release is an interesting example of marketing drivel. The name of the “web based” conversion kit is “EasySwitch.” The release alludes forebodingly to WebCT’s announcement of ceasing support for the “standard edition” in favor of the more kitchen-sink “Campus Edition,” which costs more, as the release implies, and then, near the very bottom, refers to BlackBoard as “a single reliable learning solution with long term viability.” Implying, of course, that WebCt is neither reliable nor viable—and it may well be neither, but I’m not sure BlackBoard is any better.

Were it me, I’d spend the money on smart people, including using trained graduate students as support staff and HTML folk, working with trained undergraduate HTML folk, and look at things like NNTP for discussion boards, Radio, Manilla, Perl, Apache, and MovableType–which looks like a super application for web-writing. It’s got me thinking about finding a web host that will let me use Perl.


Dave Winer uses analogy to distinguish Frontier, the environment (framework?) Manilla runs on, from Radio. He writes:

Frontier is our mainframe. It’s centralized. It includes Manila, a deep and powerful browser-based content management system. Where Radio is designed for individuals, Frontier is designed for communities and organizations, workgroups—groups of people.

I think that’s key. But it also seems to me that an organization running Frontier/Manilla might still want to license Radio for its end users.

I’m still struggling to grasp Radio. It’s so enormously powerful, with so much potential that I find it slippery.


According to the Chronicle of Higher Education, “More and more institutions are encouraging—or even requiring—students to create “electronic portfolios” that highlight their academic work and help them reflect on their campus experiences.” The article goes on to say “This month, Indiana University – Perdue University at Indianapolis and the University of California at Los Angeles formed a consortium to develop e-portfolio software”—at 10,000.00 an institution.

As much as I’ve encouraged, even evangelized, the creation of digital portfolios for graduate students, I think the consortium idea, and the price, is a bit daft. Frankly, I’d use some of the excellent blog tools that are already out there. Although BloggerPro doesn’t seem to have a license option, either Manilla or Moveable Type look possible to me as portfolio creation,management and hosting solutions. A school would create a couple of portfolio templates, make them available, add some custom locally written documentation and tutorials, encourage the interested students and faculty to learn the ten basic tags of HTML, and there you are!