CU-8696mjku8 code documentation

[thogar-computer]

This is the first go at adding some documentation on what we what to seen within the code for AMRIT.

[thogar-computer]

Task linked: CU-8696mjku8 Draft guidelines for documenting code for community approval [Timebox 2 day]

[tomlatter]

We could add this:

Use explicit and descriptive names for methods and parameters, even if they are longer, to improve readability and reduce the need for comments.
Clear naming makes code self-explanatory, minimizes ambiguity, and improves maintainability.
Example improved with explicit names:
def add_values_or_concatenate(
calendar_day_number: str,
month_number: int,
add_values: bool = False
)

And we could maybe split this document into 4 paragraphs: "Four key recommendations"

1. Documented methods

2. Consistency: There are several different option on how this documentation is presented, if possible we are asking for documentation to follow the google style.
   Whatever code documentation style is used within a repo must be continued for consistence.

3. Automation: Where possible github action will be deployed to enforce code documentation.
   GitHub Actions should check for documentation presence and format, but can avoid being overly strict on trivial methods.

4. Code refatoring: When a function or method is complex, it should ideally be broken down into smaller, more manageable components.
   This approach simplifies maintenance, as developers can focus on understanding and working with a single, isolated part of the logic without the risk of inadvertently breaking a larger, more intricate function.
   If this is not possible, say for a complex calculations, then adding inline or multiline code comments are a good solution.
   They can a reader understand what is happening and allow for a reviewer to make sure that what is commented and what is coded are in fact the same thing.
   But use inline comments sparingly and only for critical or non-obvious logic.

[thogar-computer]

@Yvanohe @tomlatter feedback actioned

[tomlatter]

Great looks good to me !
Just a small typo: "vairbale nameing" -> "Variable naming"
And in the second example "param3" in the method definition is still there