Splitting comments into standard sections
David Faden
dfaden at mac.com
Fri Apr 19 05:13:02 UTC 2002
Hi,
Is there a generally agreed upon way to split a comment up into
sections? For example, what would be a good way to mark out a section as
being a usage example or a specification? I was thinking of something
like the following:
"
Comment:
Nonevaluating conjunction. If the receiver is true, answer the value of
the argument, alternativeBlock; otherwise answer false without
evaluating the argument.
Informal Specification:
and: self: Boolean, aBlock: Block -> b: Boolean
Requires: aBlock takes no arguments and returns a Boolean
Modifies at most: the objects modified by execution of aBlock
Ensures: b is false if self is false; otherwise b is the result of
evaluating aBlock.
Example:
false and: [true]
"
The main advantage I see to labeling the comment sections in a
consistent way is making it easier for other code to pick out the
labeled sections. For example, I imagine a search program indexing
methods by example, specification, and general comment, then allowing
people to search in one or more of these categories. Also, perhaps it
would make the distinction between an inline specification and a code
example more clear to someone browsing the code.
Thank you.
David
More information about the Squeak-dev
mailing list
|