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
|