[LON-CAPA-dev] Commenting standards.
Tue, 28 May 2002 23:32:37 -0400
For posterity, I wanted to summarize the commenting standards we talked
about, and agreed to
start implementing. I think it would also be wise, when we're doing
significant work inside existing
code to bring that code into compliance. I don't think it's necessary
to mount a concerted effort to bring all
code into compliance now... just as we work on it, update.
- Each file will begin with a comment header. This header contains:
A copyright notice
Attribution of the initial author
One paragraph explanation of what the code in the module does in POD format.
- Each sub will begin with a comment header in POD format. This header
Purpose of the sub (paragraph).
Parameters including: Name, data type, direction (e.g. in, out,
Return value (type, purpose).
- Each outer level block of a sub, or main leve code starts with a
comment describing what the block does.
- Additional documentation not encompassed by all of this will be in POD
format at the end of the module.
On the whole, most modules already have this information, however in pod
form, collected at the bottom of the
module. Distributing this commenting so that documentation is close to
what is documented should improve code
Loncommon was mentioned as a module which has many of the features
described by this standard. I've
undertaken to take the module I'm working on: loncfile.pm and, after
looking at loncommon turn it into a reference
model for the commenting standard.