<div>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.</div> <div> </div> <div>why not invest some time in finding a "really" obscure example? this example of "Fraction" :</div> <div> </div> <div>"Unless you want to argue the position that part of the <BR>Fraction class's responsibility is to teach someone who doesn't know what <BR>a fraction is, what a fraction is. (In which case, I still disagree.)"</div> <div> </div> <div>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.</div> <div> </div> <div>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:</div> <div> </div> <div>1) comments which don't exactly tell me all i wish they would.</div> <div>2) no comments where i wish there were - aka... kinda like #1.</div> <div>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.</div> <div> </div> <div>4 example: i have this available:</div> <div> </div> <div>((AbstractSound sounds) at:'Guitar 1')play</div> <div> </div> <div>highlighted and "do it" sounds fine.</div> <div> </div> <div>squeak version: 3.9a-6704 -XP SP2 - amd 3800 64X2 - 1 gig ram - minor stuff...</div> <div> </div> <div>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... </div> <div> </div> <div>of course, "explaining reality" means different thing to many folks....</div> <div>i am only interested (atm) in exploring/explaining reality via this otherwise useless (2 me) computer in a way that "SOUNDS" good 2 me.</div> <div> </div> <div>that has always been my interest in using computers: MUSIC. creating/recording my own and sharing it. </div> <div> </div> <div>i have spent way too much time on distractions like fractions indeed....</div> <div> </div> <div>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 :)</div> <div> </div> <div>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.</div> <div> </div> <div>THX Much<BR><BR><B><I>Blake <blake@kingdomrpg.com></I></B> wrote:</div> <BLOCKQUOTE class=replbq style="PADDING-LEFT: 5px; MARGIN-LEFT: 5px; BORDER-LEFT: #1010ff 2px solid">On Wed, 12 Sep 2007 10:09:23 -0700, Andreas Raab <ANDREAS.RAAB@GMX.DE><BR>wrote:<BR><BR>> Numerator and denominator are no such accessors for sure. First, they <BR>> describe pretty complex objects and just because *you* know what these <BR>> mean doesn't mean everybody else does. Secondly, the denominator has <BR>> even exceptional conditions (like that it can't be zero)
which is *most <BR>> definitely* in need of commenting. I'm sorry but your example falls far <BR>> short of the point you're trying to make.<BR><BR>Disagreed. Unless you want to argue the position that part of the <BR>Fraction class's responsibility is to teach someone who doesn't know what <BR>a fraction is, what a fraction is. (In which case, I still disagree.)<BR><BR>It's not just =me= who knows what they are, it's anyone who has any <BR>business using the Fraction class. Your class comment for numerator and <BR>denominator say nothing that isn't in the dictionary.<BR><BR>Let me use a more obscure example: Say I create a voter database for a <BR>registrar and I have a variable for the precinct that the voter is in. <BR>Should I then, as an accessor comment, explain what a precinct is? Its <BR>role in the electoral college? The history of gerrymandering?[1]<BR><BR>It's not the job of code comments to explain reality, the language of <BR>what being modeled, or
common non-code abstractions (like fractions). Code <BR>comments should explain where code diverges from reality, where the <BR>variables used might be misleading, or where accepted abstractions are <BR>changed. For example, SmallInteger and Large*Integer comments usefully <BR>point out their limitations, which have nothing to do with the concept of <BR>Integers. They don't explain WHY, and go into the concept of the machine <BR>word, etc.<BR><BR>Ultimately, it's all abstraction, which one could argue demands <BR>explanantion of what is being modeled. But at some level, a programmer <BR>says, "Yes, I know this variable 'pineapple' isn't =actually= a pineapple, <BR>but it's convenient to pretend it is."<BR><BR>If you comment EVERYTHING, you end up devaluing the comments that are <BR>actually meaningful. And so, the one time the programmer is using <BR>"pineapples" to mean "hand grenades" you miss it, because you've grown <BR>accustomed to ignoring the comments, which are
mostly noise. And from what <BR>I've seen, code comment posses often end up adding a lot of noise which is <BR>at best useless, and at worst, confusing.<BR><BR>===Blake===<BR><BR>[1] I have provided that sort of basic education in supporting documents <BR>and occasionally even in class comments, but it shouldn't be mistaken for <BR>any kind of =code= documentation, and is generally a poor substitute for <BR>having actual education.<BR><BR></BLOCKQUOTE><BR><p> 
<hr size=1>Don't let your dream ride pass you by. <a href="http://us.rd.yahoo.com/evt=51200/*http://autos.yahoo.com/index.html;_ylc=X3oDMTFibjNlcHF0BF9TAzk3MTA3MDc2BHNlYwNtYWlsdGFncwRzbGsDYXV0b3MtZHJlYW1jYXI-"> Make it a reality</a> with Yahoo! Autos.