rougail/docs/structured_data/naming_convention.rst

Naming convention
=====================

.. _filenamingconvention:

File naming convention
--------------------------

The structure files in a given folder
''''''''''''''''''''''''''''''''''''''''''

For the sake of clarity, we put the structure definitions in separate files.
It's a good way to organize your rougail structures this way,
in the real world we need separate files for different topics.

For example some files like this:

A file named :file:`firefox/00-proxy.yml` structure file and file named :file:`firefox/10-manual.yml`

::

    .
    └── firefox
        ├── 00-proxy.yml
        └── 10-manual.yml

.. note:: We of course could have put everything in one file.
          Again, it is better to separate the structures in different files 
          for reasons of ordering and clarity.

Ordering your structure files
'''''''''''''''''''''''''''''''''

The order in which files are loaded is important in Rougail. 
In a given folder, files are loaded in alphabetical order.

Furthermore, for better readability of the order in which files are 
loaded into a folder, we have adopted a convention. 
To facilitate classification, we have defined a standard notation for structure file names:

::

    XX-<name>.yml

Where `XX` is a two digits integer followed by an hyphen, and `<name>` is a name that describes 
the structure that is in this file. We advise you to adopt this convention as well.

File naming convention
'''''''''''''''''''''''''''''

The is no restriction to the `<name>` name part of file name. But it is preferable to only use
lowercase ASCII letters, numbers and the `"_"` (undescore) character. 

.. _namingconvention:

Variable and family naming convention
---------------------------------------

The name of a variable and a family must be chosen carefully.
It is the path that will allow users to retrieve their defined values.
An obscure name will cause confusion.

By design, you cannot use just any character to name your variable.

The regular expression that validates our variable and family naming policy is:

.. code-block:: python

    re.compile(r"^[a-z0-9_]*$")

You can see that it is mandatory to only use lowercase ASCII letters, numbers and the `"_"` (undescore) character. 
The snake case typographic convention is therefore used.

.. attention:: The name must not starts with `_` character.