libc/docs/code_style.rst

   1 .. _code_style:
   2
   3 ===================
   4 The libc code style
   5 ===================
   6
   7 Naming style
   8 ============
   9
  10 For the large part, the libc project follows the general `coding standards of
  11 the LLVM project <https://llvm.org/docs/CodingStandards.html>`_. The libc
  12 project differs from that standard with respect to the naming style. The
  13 differences are as follows:
  14
  15 #. **Non-const variables** - This includes function arguments, struct and
  16    class data members, non-const globals and local variables. They all use the
  17    ``snake_case`` style.
  18 #. **const and constexpr variables** - They use the capitlized
  19    ``SNAKE_CASE`` irrespective of whether they are local or global.
  20 #. **Function and methods** - They use the ``snake_case`` style like the
  21    non-const variables.
  22 #. **Internal type names** - These are types which are interal to the libc
  23    implementation. They use the ``CaptilizedCamelCase`` style.
  24 #. **Public names** - These are the names as prescribed by the standards and
  25    will follow the style as prescribed by the standards.
  26
  27 Macro style
  28 ===========
  29
  30 We define two kinds of macros: **code defined** and **build defined** macros.
  31
  32 #. **Build defined** macros are generated by `CMake` or `Bazel` and are passed
  33    down to the compiler with the ``-D`` command line flag. They start with the
  34    ``LIBC_COPT_`` prefix. They are used to tune the behavior of the libc.
  35    They either denote an action or define a constant.
  36
  37 #. **Code defined** macros are defined within the ``src/__support/macros``
  38    folder. They all start with the ``LIBC_`` prefix. They are of two kinds
  39
  40    * **Properties** - Build related properties like used compiler, target
  41      architecture or enabled CPU features defined by introspecting compiler
  42      defined preprocessor defininitions. e.g., ``LIBC_TARGET_ARCH_IS_ARM``,
  43      ``LIBC_TARGET_CPU_HAS_AVX2``, ``LIBC_COMPILER_IS_CLANG``, ...
  44    * **Attributes** - Compiler agnostic attributes or functions to handle
  45      specific operations. e.g., ``LIBC_INLINE``, ``LIBC_NO_LOOP_UNROLL``,
  46      ``LIBC_LIKELY``, ``LIBC_INLINE_ASM``.
  47
  48 Inline functions defined in header files
  49 ========================================
  50
  51 When defining functions inline in header files, we follow certain rules:
  52
  53 #. The functions should not be given file-static linkage. There can be class
  54    static methods defined inline however.
  55 #. Instead of using the ``inline`` keyword, they should be tagged with the
  56    ``LIBC_INLINE`` macro defined in ``src/__support/common.h``. For example:
  57
  58    .. code-block:: c++
  59
  60      LIBC_INLINE ReturnType function_defined_inline(ArgType arg) {
  61        ...
  62      }
  63
  64 #. The ``LIBC_INLINE`` tag should also be added to functions which have
  65    definitions that are implicitly inline. Examples of such functions are
  66    class methods (static and non-static) defined inline and ``constexpr``
  67    functions.