Pattern: Comments

Context

When writing a method remember that both method users and method maintainers can be helped by accurate method documentation.

Solution

Comments help readers understand the method source. There are two types of comment: Method Comments and Code Comments.

The comment at the top of the method (the Method Comment) is for callers and maintainers of the method. It should explain:

• how to call the method
• what the method does
• what the method answers

Method users should not have to look at the code in order to find out how to use the method.

Comments within the method body (Code Comments) 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 keep them 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.

Example

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
• Method Category