[LON-CAPA-dev] Commenting standards.

[Ron Fox]

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.
Change Log
- Each sub will begin with a comment header in POD format.  This header 
describes:
Purpose of the sub (paragraph).
Parameters including: Name, data type, direction (e.g. in, out, 
modified), Purpose
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
readability.
    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.

Ron.