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
+- Preferred over cloneable non-reentrant AthAlgorithms.
+
+## Passing data between components
+ - Should be done via 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.
+
+### 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`.
+- `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, instead a `SG::AuxElement::ConstAccessor` should be used (unless they can be accessed via main versioned store interface).

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