Brian Marick has posted a wonderful essay on the subject of commenting code. "I do believe that code with comments should often be written to be more self-explanatory," he says. "But code can only ever be self-explanatory with respect to an expected reader." To illustrate, he shows an algorithm in C, then translates to the kind of Lisp a C programmer would write, then retranslates to the kind of Lisp a Lisp programmer would write. Then he walks through the Lisp code line by line, exploring how the code itself sets up and then satisfies expectations in the mind of a reader who is presumed Lisp-proficient.
The line by line analysis I gave above was inspired by the literary critic Stanley Fish. He has a style of criticism called "affective stylistics". In it, you read something (typically a poem) word by word, asking what effect each word (and punctuation mark, and line break...) will have on the canonical reader's evolving interpretation of the poem. [Exploration Through Example]
You don't run into the juxtaposition of Lisp and lit-crit every day! But as a former lit-crit person myself, I think there's a lot of merit to what Brian is saying here. The practical conclusions:
The more diverse your audience, the more likely you'll need comments. Teams will naturally converge on a particular "canonical reader", but perhaps that process could be accelerated if people were mindful of it.
Fascinating stuff, Brian.
Former URL: http://weblog.infoworld.com/udell/2003/08/30.html#a788