While it would be nice to get a list of assumptions for a piece of 
code, it is never going to happen.  The author of the code is not even 
in a position in most cases to enumerate them, and some of them are 
wrong anyway.  It would be better to have the tools somehow help us 
visualize or annotate the code with the actual pre/post conditions that 
can be inferred from the system being worked on.  Then if you write 
your test cases first (like XP suggests), the system will help you know 
what is going on.  Of course, this is just a new idea and may be "some 
magic happens".

Michael


On Oct 18, 2004, at 6:17 PM, Richard A. O'Keefe wrote:

> I wrote about a certain experience:
> 	> It would have taken the original author maybe 10 minutes
> 	> to explain what he was up to in those 20 lines.
> 	> It would have saved me a week.
> I meant "10 minutes of typing".
>
> "Darius Clarke" <DClarke at fadal.com> asked:
> 	How about "audio comments" voice recorded, with a
> 	EventRecorderMorph like walkthrough?
> 	
> ARRGH!  As someone who once had to translate between an African and
> and American (both of whom were speaking perfectly clear English, as
> far as I could tell), I'll take text over speech any day of the year.
>
> A "walkthrough" explaining "this line does X, this line does Y" and
> so on would have been totally useless redundancy.  I could see what
> the lines of code did.  What I needed to know was *under what 
> conditions
> was it OK for them to do that*, what was the code ASSUMING, not DOING.
>
> 	Do we verbally explain code (say, in a conference presentation) by
> 	reciting the code outloud?
>
> I hope not.  I really do.  Again, one reason we need comments is that 
> we
> can *see* what it is DOING, but what we need to know is what it is 
> ASSUMING.
> Any kind of explanation will involve presenting, somehow, material 
> that is
> NOT there in the code.  Perhaps even material that COULDN'T be in the 
> code.
> (References to published proofs, for example.)
>