(In the interests of full disclosure I should point out that I work  
with Steve on the staggeringly wonderful www.sophieproject.org and  
that we have had this conversation many times)

On 11-Sep-07, at 7:16 PM, Steven W Riggins wrote:

>
> The problem I have run into is that code defines what the method  
> does, not what the method was intended to do.

This seems to be the crucial point that so many "read the code"  
bigots miss. Reading the code only tells you what it does and tells  
you *nothing* about what the original writer and any subsequent  
editors intended it to do, let alone what they didn't want it to do.  
I'll not bother to grouch about how many people write such awfully  
nasty code that even after tracing it through a debugger you still  
have no clue what is actually happening.

>
> Thus, I would ask that if this is not being done now, I'd ask  
> people to evaluate this concept and look at their code from another  
> developer's eyes, and hopefully understand that a statement of  
> intention should be the first 'code' written for any method.
Exactly. Even when you are doing exploratory programming, hacking out  
code, 'in the zone' or whatever excuse you make in your feeble  
attempts to get away with being incompetent you should note some  
semblance of a spec for  the method. At least explain what you  
thought it needs to do. Preferably include a few words about known  
limitations  (like "use a linear search in an array to find all  
solutions to the dymaxxion thumb-twiddler polynomial; note that this  
will not scale well beyond a few entries") and ideally comment on any  
unknown bugs.

People have written about "Literate Programming" - Don Knuth and  
Adele Goldberg for example - for years. Dan Lanovaz has coined the  
neat description/rallying cry "Don't document the program, program  
the document!" Please, try to remember that 20 minutes after you have  
written the code you are going to be diverted by some interesting bit  
of porn-spam and when you finally get back to it you will have  
forgotten what that 'totally obvious and no comment needed' bit of  
code is about.

tim
--
tim Rowledge; tim at rowledge.org; http://www.rowledge.org/tim
Press [ESC] to detonate or any other key to explode.