/**
@page guide_developer_styleguide Style Guide
@brief Guide for the coding style used in this SDK.

The goal of this style guide is to encourage a readable and consistent coding style across the entire SDK.

@section guide_developer_styleguide_codingstyle Coding Style
@brief The coding style used in this SDK.

The coding style aims to produce code that is readable and easy to debug. An example is provided in @ref guide_developer_styleguide_codingstyle_example.

@subsection guide_developer_styleguide_codingstyle_generalguidelines General guidelines
@brief General guidelines for library style.
- All libraries should only use [ANSI adopted the ISO/IEC 9899:1999 standard.](https://en.wikipedia.org/wiki/ANSI_C#C99) features and standard library functions.
- Libraries should log extensively, but exceptions are made for pure functions.
- Code should be well-commented.
- Only <code>`/`*</code> and <code>*`/`</code> should be used to start and end comments.
- Only spaces should be used for indenting. A single indent is 4 spaces. No tab characters should be used.
- A parenthesis is usually followed by a space (see @ref guide_developer_styleguide_codingstyle_example).
- Lines of code should be less than 80 characters long, although longer lines are permitted.
- All global variables should be declared at the top of a file.
- A separator is placed between different sections of a file. The current separator is:
@code{c}
/*-----------------------------------------------------------*/
@endcode
- All files must include the config file at the top of the file <b>before any other includes</b>.
- `static` functions must have a declaration at the top of the file and be implemented before any application-facing functions.

@section guide_developer_styleguide_codingstyle_example Example File
@brief An example file that follows the coding style rules.

@code{c}
/*
 * License header pasted here.
 */

/**
 * @file example_file.c
 * @brief An example of how source files are typically written in this SDK.
 */

/* Included headers are at the top of the file. The config file include is always first. */
#include "config.h"

/* Standard includes are immediately after the config file. They are sorted alphabetically.
 * They use angle brackets <> around the file name. */

/* Standard includes. */
#include <assert.h>
#include <stddef.h>
#include <string.h>

/* This file defines `bool` for compatibility with C89 compilers. */
#if defined( __cplusplus ) || ( defined( __STDC_VERSION__ ) && ( __STDC_VERSION__ >= 199901L ) )
    #include <stdbool.h>
#elif !defined( bool ) && !defined( false ) && !defined( true )
    #define bool     int8_t
    #define false    ( int8_t ) 0
    #define true     ( int8_t ) 1
#endif

/* Library internal headers are included next. They use quotes "" around the file name. */

/* Library internal include. */
#include "private/library_internal.h"

/* Error handling include (include only when needed). */
#include "private/error.h"

/* Library application-facing headers are included last. They use quotes "" around the file name. */

/* Library include. */
#include "library.h"

/*-----------------------------------------------------------*/

/* Defined constants follow the included headers. */

/* When possible, parentheses () should be placed around constant values and a type
 * should be specified. */
#define LIBRARY_CONSTANT    ( ( int32_t ) 10 )

#define LIBRARY_FUNCTION_MACRO( argument )    \ /* Line continuators are right-aligned. */
{
    \                                           /* Function-like macros are surrounded by curly braces {}. */
    macro_body( ( argument ) );
    \                                           /* Parentheses surround macro arguments for MISRA 20.7 */
}

/*-----------------------------------------------------------*/

/* Library typedefs follow the defined constants. */

/* Forward declarations are used only when necessary. They are placed before all
 * other typedefs. */

typedef int32_t type_t;

/**
 * @brief Structs are named along with the typedef.
 */
typedef struct structType
{
    int32_t member;

    /* As usage of unions violates MISRA rule 19.2, we must document our usage
     * and justification. Unions are used here to reduce the size of this struct. */
    union /* Anonymous structs/unions are permitted only inside of other structs. */
    {
        int8_t a[ 4 ];
        int32_t b;
    };
} structType_t;

/*-----------------------------------------------------------*/

/* Declarations of static and extern functions follow the typedefs. */

static bool libraryStaticFunction( void * pArgument,
                                   size_t argumentLength );

/* External function declarations should be used sparingly (using an internal
 * header file to declare functions is preferred). */
extern int32_t Library_ExternalFunction( void * pArgument );

/*-----------------------------------------------------------*/

/* Declarations of global variables follow the static and extern function
 * declarations. Global variables are permitted, but should be avoided when
 * possible. */

/* Global variables are always initialized. */
static int globalVariable = 0;
static int pGlobalArray[ LIBRARY_CONSTANT ] = { 0 };

/*-----------------------------------------------------------*/

/* Implementations of static functions follow the global variable declarations. */

static bool libraryStaticFunction( void * pArgument,
                                   size_t argumentLength )
{
    int32_t * pLocalPointer = ( int32_t * ) pArgument;
    bool status = true;

    /* All functions make generous use of the logging library. */
    LogInfo( "Performing calculation..." );

    if( ( pArgument == NULL ) || ( argumentLength == 0 ) ) /* Note the parentheses and spacing in if statements */
    {
        LogError( "Bad parameters." );

        /* Local variable instead of a goto for error handling. */
        status = false;
    }
    else /* Note an else clause is used instead of goto for error handling */
    {
        /* Local variables should be declared at the top of a block in the narrowest scope possible. */
        int32_t localVariable = 0;
        size_t i;

        for( i = 0; i < argumentLength; i++ ) /* Note the spacing in the for loop. */
        {
            localVariable += Library_ExternalFunction( pArgument );

            LogDebug( "Current value is %d.", ( int ) localVariable );
        }

        if( localVariable < 0 )
        {
            LogWarn( "Failed to calculate positive value." );
        }

        LogInfo( "Calculation done." );
    }

    return status;
}


/* A separator is placed between all function implementations. */
/*-----------------------------------------------------------*/

/* Implementations of application-facing functions are at the bottom of the file. */

bool Library_ApplicationFunction( void ) /* Functions with no arguments have void in their argument list. */
{
    LIBRARY_FUNCTION_MACRO( globalArray );

    return true;
}

/* Separator and newline at end of file */
/*-----------------------------------------------------------*/

@endcode

*/
