Code documentation requirements and guidelines¶
The following information must be included as Doxygen formatted text in every header or module file.
- Introduction / motivation / overview of what the code does
- Input data
- Output data
- Configuration data / classes / services used (directly)
- Algorithm description (Can be reference to larsoft.org entry)
- Assumptions, pre-requisites
- institution and experiment of author/contributor(s)
Every file should have inline comments at sufficient frequency to allow readers unfamiliar with the code to be able to read and understand the code without undue effort. These comments should not be Doxygen formatted.
Each major algorithm should have a tech note describing technical details of the algorithm (can be internal to LArSoft community or published such as in http://techpubs.fnal.gov/