Class comments!?

Michael Latta lattam at mac.com
Tue Oct 19 00:43:09 UTC 2004


I resemble that remark.  While I often write working good code, being 
able to describe it so another can "get" it is not so easy.  I tend to 
assume too much understanding or competence or background knowledge on 
the part of the reader.  Part of the issue is describing a dynamic 
system with a static description.  It would be interesting to look into 
what could be done to better introduce a reader to the dynamics of a 
system.

Michael

On Oct 18, 2004, at 5:34 PM, Blake wrote:

> On Tue, 19 Oct 2004 13:06:27 +1300 (NZDT), Richard A. O'Keefe 
> <ok at cs.otago.ac.nz> wrote:
>
>> 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.
>
> Maybe. I'm not defending this guy; this is the sort of thing that I 
> would've provided pages worth of documentation for, and an algorithm I 
> would've commented out to several pages, probably.
>
> However if it was really that obscure, it might not have been easy to 
> document. I remember once writing a parse routine that was really 
> elegant, that worked really well, and yet I was very hard-pressed to 
> explain how it worked. And I'm a writer! I knew the code worked, and I 
> could prove it worked, but I couldn't explain how it worked.
>
> That hasn't happened to me a lot, but it has happened.
>
>




More information about the Squeak-dev mailing list