hmmm

Squeak List squeaklist at yahoo.com
Sat Sep 15 08:31:21 UTC 2007


wow, knowing well my own interests (personal) in using/learning smalltalk (Squeak in particular) - outside of any sort of any "higher/lower/non institution" or $ based interest, i find this "comment" interesting.
   
  why not invest some time in finding a "really" obscure example? this example of "Fraction" :
   
  "Unless you want to argue the position that part of the 
Fraction class's responsibility is to teach someone who doesn't know what 
a fraction is, what a fraction is. (In which case, I still disagree.)"
   
  is missing the point by just a TAD, or something else.... i wonder who i am speaking to here - someone pointing out the responsibility of a "class"  to "teach" anyone anything...  maybe there is a "class" somewhere, that, if attended by one and all, would make all clear - and then all would be well... but it seems that this is at least semi-demi focussed on "comments" - which i indeed agree could be improved.
   
  as a "self" who has found an interesting way to work on a somewhat difficult (maybe impossible)  problem, i have found that i often enuff run into problems with:
   
  1) comments which don't exactly tell me all i wish they would.
  2) no comments where i wish there were - aka... kinda like #1.
  3) no desire to print out the whole "image" again - just to find that i am such a fool for not knowing the exact question 2 ask - which would solve everything.
   
  4 example: i have this available:
   
  ((AbstractSound sounds) at:'Guitar 1')play
   
  highlighted and "do it" sounds fine.
   
  squeak version: 3.9a-6704 -XP SP2 - amd 3800 64X2 - 1 gig ram - minor stuff...
   
  well, after spending sooo much time looking for comments, i have found that "recreation" time (squeaking) only gets me so far. as in, i get very lost in certain places - important places of course - but i make up a new way 2 do it - but it is not perfect just yet, in case u couldn't tell.... the point being: i am not under any deadlines/pressure (except self-imposed) which in the long run, i suppose are "almost" as "important" as those imposed by some "Spiffy" boss... 
   
  of course, "explaining reality" means different thing to many folks....
  i am only interested (atm) in exploring/explaining reality via this otherwise useless (2 me) computer in a way that "SOUNDS" good 2 me.
   
  that has always been my interest in using computers: MUSIC. creating/recording my own and sharing it. 
   
  i have spent way too much time on distractions like fractions indeed....
   
  i love squeak esp - bottom line. from the amount of time i have spent on it alone, doors have opened to many things i would not have been able or interested in otherwise. wish that would be a nice cover letter :)
   
  cheers and thanks 2 all who made/make this all possible - there are are some of us "out there" doing things of interest with what y'all allowed us 2 4 free.
   
  THX Much

Blake <blake at kingdomrpg.com> wrote:
  On Wed, 12 Sep 2007 10:09:23 -0700, Andreas Raab 
wrote:

> Numerator and denominator are no such accessors for sure. First, they 
> describe pretty complex objects and just because *you* know what these 
> mean doesn't mean everybody else does. Secondly, the denominator has 
> even exceptional conditions (like that it can't be zero) which is *most 
> definitely* in need of commenting. I'm sorry but your example falls far 
> short of the point you're trying to make.

Disagreed. Unless you want to argue the position that part of the 
Fraction class's responsibility is to teach someone who doesn't know what 
a fraction is, what a fraction is. (In which case, I still disagree.)

It's not just =me= who knows what they are, it's anyone who has any 
business using the Fraction class. Your class comment for numerator and 
denominator say nothing that isn't in the dictionary.

Let me use a more obscure example: Say I create a voter database for a 
registrar and I have a variable for the precinct that the voter is in. 
Should I then, as an accessor comment, explain what a precinct is? Its 
role in the electoral college? The history of gerrymandering?[1]

It's not the job of code comments to explain reality, the language of 
what being modeled, or common non-code abstractions (like fractions). Code 
comments should explain where code diverges from reality, where the 
variables used might be misleading, or where accepted abstractions are 
changed. For example, SmallInteger and Large*Integer comments usefully 
point out their limitations, which have nothing to do with the concept of 
Integers. They don't explain WHY, and go into the concept of the machine 
word, etc.

Ultimately, it's all abstraction, which one could argue demands 
explanantion of what is being modeled. But at some level, a programmer 
says, "Yes, I know this variable 'pineapple' isn't =actually= a pineapple, 
but it's convenient to pretend it is."

If you comment EVERYTHING, you end up devaluing the comments that are 
actually meaningful. And so, the one time the programmer is using 
"pineapples" to mean "hand grenades" you miss it, because you've grown 
accustomed to ignoring the comments, which are mostly noise. And from what 
I've seen, code comment posses often end up adding a lot of noise which is 
at best useless, and at worst, confusing.

===Blake===

[1] I have provided that sort of basic education in supporting documents 
and occasionally even in class comments, but it shouldn't be mistaken for 
any kind of =code= documentation, and is generally a poor substitute for 
having actual education.



       
---------------------------------
Don't let your dream ride pass you by.    Make it a reality with Yahoo! Autos. 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20070915/fb00801c/attachment.htm


More information about the Squeak-dev mailing list