Merge branch 'AthenaGuidelines_main' into 'main'

Draft: Athena guidelines

See merge request !128

docs/athena/guidelines/index.md

+# Athena Guidelines
+
+These guidelines are intended to complement the [C++ coding guidelines](/coding-guidelines/index.md) with Athena-specific coding conventions.
+
+(Here we are thinking that it would be good to provide `AthenaExamples` corresponding to these guidelines and also real world examples in the code.)
+
+## AthReentrantAlgorithms
+- Prefer over cloneable non-reentrant AthAlgorithms in MT jobs.
+
+## Passing data between components
+ - Data should be passed between algorithms via the EventStore or ConditionsStore
+
+## EDM
+
+### ReadHandleKeys/WriteHandleKeys
+- If an Algorithm creates a collection, a `WriteHandle` for this collection should always be used to record this collect to StoreGate. The Algorithm should have a corresponding `WriteHandleKey` configurable property.
+- If an Algorithm reads a collection from StoreGate, a `ReadHandle` should always be used. The Algorithm should have a corresponding `ReadHandleKey` configurable property.
+
+!!! warning
+        Objects written to StoreGate should should not be modified once the corresponding `WriteHandle` has gone out of scope.
+        In such cases, a copy of the object with the required updates should be made instead. (Exception: See information about "Decorations" for xAOD::Containers below.)
+
+### xAOD Basics
+
+(Add information from Attila's talk in SW weekly here.)
+
+- Static variables are part of the versioned main store. They form the variables that define the baseline object and are there for every object of this type.
+- Dynamic variables are not in the versioned store. As different flavour of an object can have different additional info. For example different types of calorimeter clusters, electron, muons etc.
+- "Decorations" are a type of Dynamic variables that are added, in later stages, to a collection already in the store. Examples include modifying collections read from AOD in Derivations, or adding isolation and truth information to already reconstructed objects .
+- During the creation of a collection there is typically no need for the "Decoration" machinery as the collection is not in the store. So a `WriteDecorHandle` should not be used. (It just adds an unnecessary level of complexity by declaring surplus dependencies to the scheduler.)  In such a case use `SG::AuxElement::Accessor`.
+!!! note
+    `ReadDecorHandle` and `WriteDecorHandle` are only needed to aid scheduling in MT jobs.
+
+### Handle Rules for Shifters.
+
+!!! tip
+    - `WriteHandle` should always be used to record this collection to StoreGate. The Algorithm/component should have a corresponding `WriteHandleKey` configurable property.
+    - `ReadHandle` should always be used to read a collection from StoreGate. The Algorithm/component should have a corresponding `ReadHandleKey` configurable property.
+    - `WriteDecorHandle` must be used if a secondary algorithm (i.e. one which did not create the actual container) applies additional dynamic variables ("Decorations") to a container. `WriteDecorHandleKey` configurable properties should be used to create `WriteDecorHandle` instances.
+    - `ReadDecorHandle` should only be used to access dynamic variables applied to a container by a secondary algorithm ("Decorations"). `ReadDecorHandleKey` configurable properties should be used to create `ReadDecorHandle` instances.
+
+!!! warning
+    - `WriteDecorHandle` should not be used for additional dynamic variables applied by the same algorithm which created the container, instead `SG::AuxElement::Accessor` should be used (unless they can be accessed via main versioned store interface).
+    - `ReadDecorHandle` should not be used to access dynamic variables applied by the algorithm which created the container (this includes the case where the decorated object is read from the input file), instead a `SG::AuxElement::ConstAccessor` should be used (unless they can be accessed via main versioned store interface).
+    - Prefer `SG::AuxElement::Accessor` over `SG::AuxElement::Decorator` unless  `WriteDecorHandle` should be used.
+
+
+## Header files should be self-sufficient.
+To ensure this is true, it is better to include headers in the following order:
+- Specific local headers
+- Framework headers
+- Other library and then std:: includes last (memory, vector, string etc)
+
+see, for example, https://stackoverflow.com/questions/2762568/c-c-include-header-file-order

mkdocs.yml

@@ -86,6 +86,7 @@ nav:
         - athena/performance/vtune.md
     - athena/gpu/index.md
     - athena/io/index.md
+    - athena/guidelines/index.md
   - Developers:
       - athena/developers/index.md
       - athena/developers/releases.md