docs/codingstyle.rst

   1 Coding Style
   2 ============
   3
   4 Mesa is over 20 years old and the coding style has evolved over time.
   5 Some old parts use a style that's a bit out of date. Different sections
   6 of mesa can use different coding style as set in the local EditorConfig
   7 (.editorconfig) and/or Emacs (.dir-locals.el) file. Alternatively the
   8 following is applicable. If the guidelines below don't cover something,
   9 try following the format of existing, neighboring code.
  10
  11 Basic formatting guidelines
  12
  13 -  3-space indentation, no tabs.
  14 -  Limit lines to 78 or fewer characters. The idea is to prevent line
  15    wrapping in 80-column editors and terminals. There are exceptions,
  16    such as if you're defining a large, static table of information.
  17 -  Opening braces go on the same line as the if/for/while statement. For
  18    example:
  19
  20    .. code-block:: c
  21
  22       if (condition) {
  23          foo;
  24       } else {
  25          bar;
  26       }
  27
  28 -  Put a space before/after operators. For example, ``a = b + c;`` and
  29    not ``a=b+c;``
  30 -  This GNU indent command generally does the right thing for
  31    formatting:
  32
  33    .. code-block:: console
  34
  35       indent -br -i3 -npcs --no-tabs infile.c -o outfile.c
  36
  37 -  Use comments wherever you think it would be helpful for other
  38    developers. Several specific cases and style examples follow. Note
  39    that we roughly follow `Doxygen <http://www.doxygen.nl>`__
  40    conventions.
  41
  42    Single-line comments:
  43
  44    .. code-block:: c
  45
  46       /* null-out pointer to prevent dangling reference below */
  47       bufferObj = NULL;
  48
  49    Or,
  50
  51    .. code-block:: c
  52
  53       bufferObj = NULL;  /* prevent dangling reference below */
  54
  55    Multi-line comment:
  56
  57    .. code-block:: c
  58
  59       /* If this is a new buffer object id, or one which was generated but
  60        * never used before, allocate a buffer object now.
  61        */
  62
  63    We try to quote the OpenGL specification where prudent:
  64
  65    .. code-block:: c
  66
  67       /* Page 38 of the PDF of the OpenGL ES 3.0 spec says:
  68        *
  69        *     "An INVALID_OPERATION error is generated for any of the following
  70        *     conditions:
  71        *
  72        *     * <length> is zero."
  73        *
  74        * Additionally, page 94 of the PDF of the OpenGL 4.5 core spec
  75        * (30.10.2014) also says this, so it's no longer allowed for desktop GL,
  76        * either.
  77        */
  78
  79    Function comment example:
  80
  81    .. code-block:: c
  82
  83       /**
  84        * Create and initialize a new buffer object.  Called via the
  85        * ctx->Driver.CreateObject() driver callback function.
  86        * \param  name  integer name of the object
  87        * \param  type  one of GL_FOO, GL_BAR, etc.
  88        * \return  pointer to new object or NULL if error
  89        */
  90       struct gl_object *
  91       _mesa_create_object(GLuint name, GLenum type)
  92       {
  93          /* function body */
  94       }
  95
  96 -  Put the function return type and qualifiers on one line and the
  97    function name and parameters on the next, as seen above. This makes
  98    it easy to use ``grep ^function_name dir/*`` to find function
  99    definitions. Also, the opening brace goes on the next line by itself
 100    (see above.)
 101 -  Function names follow various conventions depending on the type of
 102    function:
 103
 104    +---------------------+------------------------------------------+
 105    | Convention          | Explanation                              |
 106    +=====================+==========================================+
 107    | ``glFooBar()``      | a public GL entry point (in              |
 108    |                     | :file:`glapi_dispatch.c`)                |
 109    +---------------------+------------------------------------------+
 110    | ``_mesa_FooBar()``  | the internal immediate mode function     |
 111    +---------------------+------------------------------------------+
 112    | ``save_FooBar()``   | retained mode (display list) function in |
 113    |                     | :file:`dlist.c`                          |
 114    +---------------------+------------------------------------------+
 115    | ``foo_bar()``       | a static (private) function              |
 116    +---------------------+------------------------------------------+
 117    | ``_mesa_foo_bar()`` | an internal non-static Mesa function     |
 118    +---------------------+------------------------------------------+
 119
 120 -  Constants, macros and enum names are ``ALL_UPPERCASE``, with \_
 121    between words.
 122 -  Mesa usually uses camel case for local variables (Ex:
 123    ``localVarname``) while Gallium typically uses underscores (Ex:
 124    ``local_var_name``).
 125 -  Global variables are almost never used because Mesa should be
 126    thread-safe.
 127 -  Booleans. Places that are not directly visible to the GL API should
 128    prefer the use of ``bool``, ``true``, and ``false`` over
 129    ``GLboolean``, ``GL_TRUE``, and ``GL_FALSE``. In C code, this may
 130    mean that ``#include <stdbool.h>`` needs to be added. The
 131    ``try_emit_*`` method ``src/mesa/state_tracker/st_glsl_to_tgsi.cpp``
 132    can serve as an example.