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.
Figure 1. LArSoft relationships - 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”),
- date
- 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. Write code that is thread safe by asking: What is the context in which this function will be called? For more information, please see: Making Code Thread-Safe by Kyle Knoepfel and Introduction to multi-threading and vectorization by Matti Kortelainen.
8. LArSoft uses the Continuous integration (CI) system to allow users to specify and automate the execution of tests of LArSoft software. For more information, please see https://larsoft.org/continuous-integration/
For more information on design principles and practices, please see: