web page hit counter

Thursday, May 22, 2008

Coding and Comments

Some recent Twitter posts by Adam Keys got me thinking about the role of comments in code. Good and consistent coding style that reflects a solid development philosophy helps eliminate the need for many kinds of comments. Capturing requirements in a formal-ish way (through the use of techniques like Behavior and Domain Driven Design) eliminates even more. If important requirements can be captured formally in a "live"[1] way, they generally should be.

But (a) you're not always in a situation where formal-ish requirements capture is possible and (b) there is some information that can't be captured formally.

It's clear what needs to be done in the long term about (a), but in the mean time if you're going to have static text, it's good to have it as close to the code as possible. Comments let you do that.

It's not so clear what can be done about (b). Even if you've read the code and grok it 100%, there are situations ("Although it's irrational, as of Oct. 18 2005, the accounting department insists we use HTTP basic auth without SSL") in which the code is not enough. Anything to do with people and their motivations, really.

So, imagine yourself as a slightly-less-clever-than-you-think-you-are future reader of your own code. Imagine that you're generally familiar with the application, have read the code in some detail, and understand the development philosophy (hopefully) baked in throughout the system. If you're still thinking "WTF?!" then put in a comment. If it takes a full paragraph to explain the awful circumstances that led you write something impenetrable, then do it. Your future self will thank you.

[1] In post-Singularity world, code executes you. Until then, you can't really refactor, trace, test or formally analyze static natural-language text like comments or (shudder) external requirements docs. Natural language isn't "live".

You should follow me on twitter here.

Thursday, May 15, 2008

Dallas Social Network Technology Event

Based in or around Dallas? Serious about developing an application based on social network technology? Was Facebook Dev Garage too Facebook specific for you? We're planning a get-together in early June you might be interested in. It's looking like the evening of Tuesday, June 3rd starting at 7:00 and going till about 9:00 at the ritzy Sabre campus in scenic Southlake, TX:

Sabre Holdings
3150 Sabre Dr. Southlake, TX 76092
(Campus Directions: Gate , Parking , Entrance)

When you get to the security gate, tell the guard you're with the Social Network Technology event, and you're in like Flynn.

Wiki at:


Facebook event page at:


Current agenda is a quick round of introductions at 7:00, some demos, some discussion, and a followup at a local tasty beverage establishment. Leave a message on the Facebook event wall if you're interested in demoing or have a particular topic you'd like to focus on.

You should follow me on twitter here.