Coding Standards
================

Nexus follows strict coding standards for quality and safety.

C Standard
----------

- C11 for source code
- C++17 for tests

Code Formatting
---------------

The project uses clang-format for automatic code formatting. Run ``clang-format``
before committing code.

See also: ``.kiro/steering/comment-standards.md`` for detailed comment guidelines.

Indentation
~~~~~~~~~~~

- Use 4 spaces for indentation (no tabs)
- Indent case labels inside switch statements
- Do not indent preprocessor directives

Line Length
~~~~~~~~~~~

- Maximum line length: 80 characters
- Break long lines at appropriate points

Braces
~~~~~~

Use attached braces (K&R style)::

    if (condition) {
        /* code */
    } else {
        /* code */
    }

    void function(void) {
        /* code */
    }

Spaces
~~~~~~

- Space after control keywords: ``if (``, ``for (``, ``while (``
- No space after function names: ``func()``
- No space after casts: ``(int)value``
- Two spaces before trailing comments
- Space around binary operators: ``a + b``, ``x = y``

Pointer Alignment
~~~~~~~~~~~~~~~~~

Pointers align to the left (with the type)::

    int* ptr;           /* Correct */
    char* str;          /* Correct */

Empty Lines
~~~~~~~~~~~

- Maximum one consecutive empty line
- Use empty lines to separate logical sections

Naming Conventions
------------------

- Functions: ``module_action_object()`` (e.g., ``hal_gpio_init()``)
- Types: ``module_type_t`` (e.g., ``hal_status_t``)
- Macros: ``MODULE_MACRO_NAME`` (e.g., ``HAL_OK``)
- Constants: ``MODULE_CONSTANT`` (e.g., ``HAL_GPIO_PORT_MAX``)
- Static variables: ``s_variable_name`` prefix
- Global variables: ``g_variable_name`` prefix (avoid when possible)

Documentation
-------------

All public APIs must have Doxygen comments. This project uses ``\`` style
Doxygen tags (not ``@`` style).

Tag Alignment
~~~~~~~~~~~~~

All Doxygen tags must be aligned to column 20 (17 spaces after ``*``).
This ensures consistent formatting across the codebase::

    /**
     * \brief           Brief description starts at column 20
     * \param[in]       param: Parameter description
     * \param[out]      result: Output parameter description
     * \return          Return value description
     */

File Header Format
~~~~~~~~~~~~~~~~~~

Every source file must have a file header comment.

**Header files (.h)** - Minimal format::

    /**
     * \file            filename.h
     * \brief           Brief description of the file
     * \author          Nexus Team
     */

**Source files (.c)** - Full format with version and copyright::

    /**
     * \file            filename.c
     * \brief           Brief description of the file
     * \author          Nexus Team
     * \version         1.0.0
     * \date            2026-01-12
     *
     * \copyright       Copyright (c) 2026 Nexus Team
     *
     * \details         Detailed description of the file contents
     *                  and purpose. Can span multiple lines.
     */

Header Files (.h)
~~~~~~~~~~~~~~~~~

Header files contain full API documentation including parameters and return values::

    /**
     * \brief           Create a mutex
     * \param[out]      handle: Pointer to store mutex handle
     * \return          OSAL_OK on success, error code otherwise
     */
    osal_status_t osal_mutex_create(osal_mutex_handle_t* handle);

Source Files (.c)
~~~~~~~~~~~~~~~~~

Source files should NOT duplicate ``\param`` and ``\return`` documentation
from headers. Use only ``\brief``, ``\details``, and ``\note``::

    /**
     * \brief           Create a mutex
     * \details         Allocates and initializes a new mutex object.
     *                  The mutex is created in unlocked state.
     * \note            Thread-safe function.
     */
    osal_status_t osal_mutex_create(osal_mutex_handle_t* handle) {
        /* Implementation */
    }

Section Comments
~~~~~~~~~~~~~~~~

Use section comments to organize code into logical blocks. The separator line
must be exactly 77 characters (``/*`` + 75 characters + ``*/``)::

    /*---------------------------------------------------------------------------*/
    /* Section Name                                                              */
    /*---------------------------------------------------------------------------*/

**Important**: Do NOT use ``/*===...===*/`` style separators. Always use
``/*---...---*/`` for consistency.

Inline Comments
~~~~~~~~~~~~~~~

Use ``/* comment */`` style for inline comments, not ``//``::

    int value = 0;  /* Initialize to zero */

Macro Comments
~~~~~~~~~~~~~~

Use Doxygen block comments or inline comments for macros::

    /**
     * \brief           Maximum buffer size
     */
    #define MAX_BUFFER_SIZE 256

    /* Or use inline style */
    #define MAX_BUFFER_SIZE 256  /**< Maximum buffer size */

Static Functions
~~~~~~~~~~~~~~~~

Static functions use simplified comments with only ``\brief``::

    /**
     * \brief           Internal helper function description
     */
    static void internal_helper(void) {
        /* Implementation */
    }

Prohibited Practices
~~~~~~~~~~~~~~~~~~~~

The following practices are NOT allowed:

- Using ``@`` style Doxygen tags (use ``\`` instead)
- Using ``//`` single-line comments (use ``/* */`` instead)
- Using ``/*===...===*/`` section separators (use ``/*---...---*/`` instead)
- Duplicating ``\param`` and ``\return`` in source files (only in headers)

MISRA C
-------

Code should comply with MISRA C:2012 guidelines.