1Coding Style & Guidelines
2=========================
3
4The following sections contain |TS| coding guidelines for different types of file. They are continually evolving
5and should not be considered "set in stone". Feel free to question them and provide feedback.
6
7To help configuring text editors the project comes with "`EditorConfig`_" file(s). (:download:`../../.editorconfig`).
8
9Common Rules
10------------
11
12The following rules are common for all types of text file, except where noted otherwise:
13
14#. Files shall be **UTF-8** encoded.
15#. Use **Unix** style line endings (``LF`` character)
16#. The primary language of the project is English. All comments and documentation must be in this language.
17#. Trailing whitespace is not welcome, please trim these.
18
19C Rules
20-------
21
22C source code rules are base on the *Linux Coding Style* (See: |LCS|). The following deviations apply:
23
245. |TS| follows *ISO/IEC 9899:1999* standard with |ACLE| version *Q3 2020* extensions.
25#. Line length shall not exceed 100 characters.
26#. Use `snake_case`_ for function, variable and file names.
27#. Each file shall be "self contained" and include header files with external dependencies. No file shall depend on
28   headers included by other files.
29#. Include ordering: please include project specific headers first and then system includes. Please order the files
30   alphabetically in the above two groups.
31#. All variables must be initialized.
32
33C source files should include a copyright and license comment block at the head of each file. Here is an example::
34
35   /*
36    * Copyright (c) 2020-2023, Arm Limited and Contributors. All rights reserved.
37    *
38    * SPDX-License-Identifier: BSD-3-Clause
39    */
40
41Boring stuff is not for smart people and the project uses the `Clang-Format`_ code beautifier to easy formatting the
42source. (See :download:`../../.clang-format`)
43
44CMake Rules
45-----------
46
47Cmake files (e.g. CMakeLists.txt and .cmake) should conform to the following rules:
48
491.  CMake file names use `CamelCase`_ style.
50#. Indent with tabs and otherwise use spaces. Use 4 spaces for tab size.
51#. Use LF as line end in CMake files.
52#. Remove trailing whitespace.
53#. Maximum line length is 128 characters.
54#. When complicated functionality is needed prefer CMake scripting over other languages.
55#. Prefix local variables with `_`.
56#. Use functions to prevent global name-space pollution.
57#. Use `snake_case`_ for function and variable names.
58#. Use the ``include_guard()`` CMake function when creating new modules, to prevent multiple inclusion.
59#. Use self contained modules, i.e. include direct dependencies of the module.
60#. Use the Sphinx CMake domain for in-line documentation of CMake scripts. For details please refer to the
61   `CMake Documentation`_.
62
63Each file should include a copyright and license comment block at the head of each file. Here is an example::
64
65   #-------------------------------------------------------------------------------
66   # Copyright (c) 2020-2023, Arm Limited and Contributors. All rights reserved.
67   #
68   # SPDX-License-Identifier: BSD-3-Clause
69   #
70   #-------------------------------------------------------------------------------
71
72Restructured Text Rules
73-----------------------
74
75Please refer to :doc:`/developer/writing-documentation`.
76
77--------------
78
79.. _`CamelCase`: https://hu.wikipedia.org/wiki/CamelCase
80.. _`snake_case`: https://en.wikipedia.org/wiki/Snake_case
81.. _`CMake Documentation`: https://github.com/Kitware/CMake/blob/master/Help/dev/documentation.rst
82.. _`EditorConfig`: https://editorconfig.org/
83.. _`Clang-Format`: https://clang.llvm.org/docs/ClangFormat.html
84
85*Copyright (c) 2020-2023, Arm Limited and Contributors. All rights reserved.*
86
87SPDX-License-Identifier: BSD-3-Clause
88