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