Coding Style & Guidelines
=========================

The following sections contain |TS| coding guidelines. They are continually evolving and should not be considered "set
in stone". Feel free to question them and provide feedback.

The |TS| project uses multiple "domains" (textual content types, like programming languages) and each defines its own
rules.

To help configuring text editors the project comes with "`EditorConfig`_" file(s). (:download:`../../.editorconfig`).

Shared rules
------------

The following rules are common for all domains, except where noted otherwise:

#. Files shall be **UTF-8** encoded.
#. Use **Unix** style line endings (``LF`` character)
#. The primary language of the project is English. All comments and documentation must be in this language.
#. Trailing whitespace is not welcome, please trim these.

C Domain
--------

C source code rules are base on the *Linux Coding Style* (See: |LCS|). The following deviations apply:

5. |TS| follows *ISO/IEC 9899:1999* standard with |ACLE| version *Q3 2020* extensions.
#. Line length shall not exceed 100 characters.
#. Use `snake_case`_ for function, variable and file names.
#. Each file shall be "self contained" and include header files with external dependencies. No file shall depend on
   headers included by other files.
#. Include ordering: please include project specific headers first and then system includes. Please order the files
   alphabetically in the above two groups.
#. All variables must be initialized.

Boring stuff is not for smart people and the project uses the `Uncrustify`_ code beautifier to easy formatting the
source. (See :download:`../../.uncrustify.cfg`)

CMake domain
------------

11. CMake file names use `CamelCase`_ style.
#. Indent with tabs and otherwise use spaces. Use 4 spaces for tab size.
#. Use LF as line end in CMake files.
#. Remove trailing whitespace.
#. Maximum line length is 128 characters.
#. When complicated functionality is needed prefer CMake scripting over other languages.
#. Prefix local variables with `_`.
#. Use functions to prevent global name-space pollution.
#. Use `snake_case`_ for function and variable names.
#. Use the ``include_guard()`` CMake function when creating new modules, to prevent multiple inclusion.
#. Use self contained modules, i.e. include direct dependencies of the module.
#. Use the Sphinx CMake domain for in-line documentation of CMake scripts. For details please refer to the
   `CMake Documentation`_.

.. todo:: Explain CMake return values and parent scope concept in more detail.

Restructured Text Domain
------------------------

Please refer to :doc:`/developer/writing-documentation`.

--------------

.. _`CamelCase`: https://hu.wikipedia.org/wiki/CamelCase
.. _`snake_case`: https://en.wikipedia.org/wiki/Snake_case
.. _`CMake Documentation`: https://github.com/Kitware/CMake/blob/master/Help/dev/documentation.rst
.. _`EditorConfig`: https://editorconfig.org/
.. _`Uncrustify`: https://github.com/uncrustify/uncrustify

*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*

SPDX-License-Identifier: BSD-3-Clause