Main comment stating the purpose of this class and relevant relationship to other classes.
Possible useful expressions for doIt or printIt.
Structure:
instVar1 type – comment about the purpose of instVar1
instVar2 type – comment about the purpose of instVar2
Any further useful comments about the general approach of this implementation.
Contrary to popular belief it is meaningless as a comment and should be replaced.
It is, however, a pretty good reminder of what you might replace it with.
The class comment should be the key entry point for understanding the class.
Please identify any special methods which give examples, documentation, unit tests or other illuminating sections of code.
Class comments are easy to add: Just select the question mark box beneath the highlighted class (?). Update and then accept the comment.
Method comments
A comment consists of any sequence of any characters enclosed by the double quote characters (")
A double quote characters may be embedded within a comment by doubling it ("")
Comments may span multiple lines
Comments are considered whitespace and may appear anywhere within the body of a method that whitespace is allowed.
There should be a comment at the top of every method describing:
What the method does
What classes of objects are valid arguments
What is the class of the value returned
Special considerations
There should be comments explaining any section of code that a less experienced Smalltalk programmer may not recognize
In general, a programmer reading your method should not have to search through all references to your parameters or implementations of called methods to determine what is going on.
