Usefull comments (WAS Meaning of Float>>closeTo:)
nicolas cellier
ncellier at ifrance.com
Sun Mar 4 00:22:39 UTC 2007
By the way, while watching Player's code what a usefull comment!
setHeading: newHeading
"Set the heading as indicated"
One should better explain me expected unit and other conventions (0
upscreen ? positive clockwise ? )
Something not really indicated.
Inquiring Morph>>heading is helpless
heading
"Return the receiver's heading (in eToy terms)"
If i browse Morph comments, nothing.
I then click TransformMorph link and there i get
"Rotation and scaling are relative to the local origin, (0 at 0)."
Fortunately Kedama is more explicit, and win a Medals
heading
"Answer my heading in degrees."
Also senders of #setHeading: will provide informations.
Still i know nothing about zero and clockwise but for that i can reverse
engineer the code...
And #setHeadingTheta: tells me there is another convention lying in the
system, but nothing more...
Well easy to criticize, but i think we are all responsible of providing
better comments.
- not paraphrasing the code or the method name
- not to long (better give a reference to a document, tutorial or whatever)
- clues about limitations, non trivial implementation choices...
Or maybe like pair programming, programmer should not write the comment.
Nicolas
More information about the Squeak-dev
mailing list
|