Style Code

This file will describe code styles used in this repos to make code and documentation more homogeneous.

Versionning & Contribution

When developping and especially when commiting you work, try to make "beautiful" commit, with a title and a description of what is done.

If your modification can be written in one line title (i.e. less than 50 char), for instance, writing documentation in the README.md, avoid commit message like "Update README.md", prefer "Update section XXXX in README.md" or even better :

Update section configuration in README.md

Add/Update section configuration witch describe how to configure your prompt and
link to the related documentation.

Sometime you are not used to do this or you may not have time or you have a huge commit which only do one thing (for instance, 30 update files, which is only updating documentation).

Thus, above advice about commit are not mandatory, but merge request MUST follow the "beautiful" merge request guideline. Merge request with only title "merge branch on master" will need to be updated before being accepted.

Finally, when contributing, i.e. propose a merge request, ensure that your personal configuration files (your .envrc files for instance) are not versionned.

Configuration Files

Configuation files MUST be commented. If you add or update configuration files, please provide comments above the variable to describe the use of variable and, if needed, why you choose these values. This is especially true when deactivatin testing tools error or warnings.

Python Files

Python files should respect PEP8. To ensure this, the CI use flake8 and pylint.

Moreover, if new features are added within python files, these features should be tested. Test are realized using pytest.

Ansible Roles

Markdown mkdocs flavor

When writing markdown documentation for mkdocs, please prefer following syntax:

For hyperlink, please use the following syntax:

[Text Content][ext_hyperlink_key]
[Another Text Content][int_hyperlink_key]

[ext_hyperlink_key]: https://external.link
[int_hyperlink_key]: ../relative/path.md

For image, a lightbox plugin is installed. So to allow lightboxing of image in mkdocs documentation, please use the following syntax:
```
![!Image Caption][image_key]

[image_key]: ../relative/path/to/image.png
```
For the documentation, multiple markdown extension have been installed such as:
- Admonition Admonition is an extension included in the standard Markdown library that makes it possible to add block-styled side content to your documentation, e.g. summaries, notes, hints or warnings.
- Footnotes Footnotes is another extension included in the standard Markdown library. As the name says, it adds the ability to add inline footnotes to your documentation.
- Metadata Metadata is an extension included in the standard Markdown library that makes it possible to control certain properties in a page-specific context, e.g. the page title or description.
- Permalinks Permalinks are a feature of the Table of Contents extension, which is part of the standard Markdown library.
- PyMdown PyMdown Extensions is a collection of Markdown extensions that add some great missing features to the standard Markdown library.
- mermaid Mermaid is a tool that generates diagrams and charts, from markdown-inspired text definitions

Allowing you to enrich the content of the documentation.

Bash Scripting

Bash script follow some code styles which are describe below:

When using function or method, for, while, case or if, put respectively {, do, do, esac and then below the condition to test.

Example (Click to reveal)

functions name()
{
  case $1 in
    [a-z]*)
      echo "Alphabet"
      ;;
    [0-9]*)
      if [[ $1 -lt 5 ]]
      then
        echo "Number less than 5"
      else
        echo "Number greater than 5"
      fi
      ;;
    *)
      echo "Unknown"
      ;;
  esac
}

When using for or while loop, prefer using variable starting with i followed by an explicit name than simply i, j, etc.
Example (Click to reveal)
```
age_array("10" "15" "17" "22" "35" "40")
for i_age in "${age_array[@]}"
do
  echo "You are ${i_age} years old."
done
```

Use 2 indentation space when defining a scope (method, loop, condition, etc.).

Example (Click to reveal)

func()
{
  people=("Alice" "Bob" "Carol" "David" "Eve")
  for i_people in "${people[@]}"
  do
    if [[ ${i_people} =~ a ]]
    then
      echo "${i_people}"
    else
      echo "I do not tell people name which does not have an 'a'"
    fi
  done
}

When using "advanced" bashism, such as string substitution, write a comment above describing what you do in human readable format.

For more informations about what I consider string substitution, see tldp.org-String Manipulation, this is not mandatory but is here to help people not used to these syntax to understand what is done.
Example (Click to reveal)
```
A="abcdabcda"
# Replace 'cd' in ${A} by 'zy'
B=${A/cd/zy}
echo $B
# Remove everything in before the last occurence of 'a'
C=${A##*a}
# Remove everything after the first occurence of c
D=${A%%c*}
```

Document your method with a "docstring" like.

Example (Click to reveal)

function func_name()
{
  # This is a docstring like expliciting what func_name do
  # *PARAM $1: string, explicit description of the required (`*`) expected string
  # PARAM $2: string, explicit description of the optional expected string
  # NO PARAM: -> Means that NO PARAM is required or optional for this
  #             function
}

Do not write more that 80 char lines of code, except when there is no other options or when using echo.

Why ? (click to reveal)
Because I often have two or three code files open in splitted screen in vim, thus showing only 80 char per file.
All variable should be in lowercase execpt for configuration and constant variables that can be set in configuration files host/ folder which are in uppercase. Prefer to use _ between words in variable name. And when using variables, use {} around the variable usage.
Why ? (click to reveal)
The lowercase is to make differences between constant/user defined variables and the computation variables.

The _ between word is to make variable name more human readable.

The {} may add a heavy layout of reading but as I use lots of arrays and string manipulation, I now tends to use them all the time. Moreover this avoid issues like shown below:
```
var="filename.sh"
# When not using `{}`, line below will search for value of variable
# `var_temp` instead of printing the value of ${var} + "_temp"
echo "$var_temp"
# While this line print ${var} + "_temp"
echo "${var}_temp"
```
Example (click to reveal)
```
git_username="Firstname Lastname"
git_usermail="username@domain.tld"
echo "${git_username} < ${git_usermail} >"
```
End your code files with a vim modeline.
Example (click to reveal)
I usually tend to be explicit in my modeline:
```
# ***********************************
# EDITOR CONFIG
# vim: ft=sh: ts=2: sw=2: sts=2
# **********************************
```
But a shorten modeline is valid too:
```
# vim: ft=sh: ts=2: sw=2: sts=2
```
This modeline tells to vim that
- ft=sh: filetype is sh
- ts=2: tabstop should be 2 space wide
- sw=2: shiftwidth should be 2 space wide
- sts=2: replace tab by a 2 space indent

Important

As stated above, this code styles are not mandatory but here to provide guidelines. Moreover, I'm open to discussion to use other guidelines.

Below is an example using these code styles:

#!/bin/bash

# Description of the script. Which simply print the content of an array but
# replace value "item" of each cells by "toto-item" if item index is pair and
# "tata-item" if index is odd

method()
{
  # Print value of array but replace "item" by toto-item if item is pair and
  # tata-item if item is odd.
  # NO PARAM

  local my_array("item0" "item1" "item2" "item3")
  local idx_item=""

  for i_elem in "${my_array[@]}"
  do
    # Extract index of item that is at the end of the string
    idx_item=${i_elem##item}
    if [[ $(( idx_item % 2 )) -eq 0 ]]
    then
      # Replace item by toto-item
      echo "${i_elem/item/toto-item}"
    else
      # Replace item by tata-item
      echo "${i_elem/item/tata-item}"
    fi
  done
}

# *****************************************************************************
# EDITOR CONFIG
# vim: ft=sh: ts=2: sw=2: sts=2
# *****************************************************************************

Last update: August 25, 2020