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