Navigation: Appendix B: Dolphin Pattern Book > Method Patterns >
When writing a method remember that both method users and method maintainers can be helped by accurate documentation. However, verbose comments tend not to be kept up to date with code changes and lend little to the overall readability of a method.
Concise method comments help readers understand the method source. There are two types of method comment:
|1.||The comment at the top of the method is for callers and maintainers of the method. Method users should not have to look at the code in order to find out how to use the method so it should explain:|
|•||how to call the method|
|•||what the method does|
|•||what the method answers|
|2.||Comments within the method body are for code maintainers only. These should describe sections of the method which are not readily understandable from the source. Don't write code comments which simply restate the code. Write concise comments and make sure they are kept up-to-date with the code.|
The method comment in a Private Method should begin with "Private - ". There is no equivalent convention for public methods.
The Collection class contains the following method comment:
"Answer a new Collection, like the receiver,
that is the intersection of the elements of the
receiver and aCollection."
^self select: [ :element | aCollection includes: element ]