Class comments!?

Blake blake at kingdomrpg.com
Tue Oct 19 03:58:10 UTC 2004


On Mon, 18 Oct 2004 17:43:09 -0700, Michael Latta <lattam at mac.com> wrote:

> 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.

I'm glad I'm not the only one that happens to.

I do a lot of work with the Institutes for the Achievement of Human  
Potential in Philadelphia (iahp.org) which has been devoted for the past  
fifty years or so to the study of how the brain develops and how children  
learn. One of those things they talk about is people who "get math". If  
you ask someone like this to do one of those 8th grade geometry proofs,  
they'll simply agree with you, "Yes, that is true." If you ask them to  
actually do the proof, you'll get a blank stare. Of course it's true.

In other words, they simply see it, the way they see 32,879 - 12,645 =  
20,234. They'd have trouble understanding why proof of something so  
self-evident would ever be needed.

So, on the one hand, you have people who are going to grasp the purpose  
and meanings of code and not see the need for documentation. On the other,  
you have people who are going to need things spelled out. And the two are  
going to have a very hard time communicating.

Then on the third hand, you have a situation like the one I described,  
where I have page after page of scribblings that even I don't understand,  
resulting in some really nice code that works, but I couldn't explain how  
other than "Well...it does." Sort of like a QuickSort.<s>








More information about the Squeak-dev mailing list