LArSoft design principles and practices
- Detector interoperability – The most important design objective for the LArSoft project is to define and use common interfaces for accessing detector-specific configuration information and functionality. This applies to geometry, channel mappings, LAr properties, E-field map, etc. The second part of this is to write algorithms that use only these common interfaces.
- Separation of framework and algorithm code – Encapsulate algorithms, configuration, tools and utilities into a layer that is independent of the art framework and external products as shown in the following diagram.
- Use of standardized algorithm interfaces – Define common interfaces for well-defined steps in the workflow to promote modularity and layering of algorithms.
- Modularity – Build sophistication by applying algorithms in a layered, iterative structure.
- Design / write testable units of code – Include unit and integration testing in the development process.
- Follow the practice of continuous integration.
- Perform automated, broad-scale testing at frequent intervals in order to catch unintended side-effects quickly.
- Document code in the source files – at a minimum include at the top of all header files:
- Name of the author(s),
- experiment affiliation (“from experiment”),
- institutional affiliation (“from institution”),
- information about what this code does, what it requires as input, what assumptions it makes (i.e. pre-conditions), and what output it produces.
In stating affiliations, it’s important to not imply that the code is “for” a given experiment — some people will assume that means it doesn’t apply to them, so better to say it’s ‘from experiment Y’ rather than ‘for experiment Y.’ This is useful in giving credit for developing common code along with documenting algorithms or services at LArSoft.org.
To mark major changes, new (or existing) authors should update this information including a revision history.
7. Code repositories can be framework-dependent or framework-independent (also known as shared repositories). Even framework-independent ones are dependent on canvas which provides I/O operations for the full art framework and the lightweight gallery framework. Another LArSoft repository type is product-interface which provides direct access to a particular package (such as Pandora or LArWireCell) without making any other parts of LArSoft dependent on them. For more information on code repositories, please see the redmine wiki.
For more information, please see: Erica Snider’s introduction to LArSoft