Last updated at 2:33 am UTC on 11 April 2007
mergeMe into Documentation within the Image
The default class comment is:
Main comment stating the purpose of this class and relevant relationship to other classes.
Possible useful expressions for doIt or printIt.
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.
- 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.
Reflection: retrieving comments from the Class
- Send the "comment" message to a class
- "Integer comment"
- "(100 class) comment"