Navigation:  Appendix B: Dolphin Pattern Book > Method Patterns >

Method Comment

Previous pageReturn to chapter overviewNext page

Context

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.

Solution

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.

Known Uses

The Collection class contains the following method comment:

intersection: aCollection

  "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 ]

 

Related Patterns

Method Name