C NAMING & STYLE GUIDELINES

Version 0.1

Customer Internal Use

Version Date 15/06/2018

Related template
1.0
version
 C NAMING & STYLE GUIDELINES

CHANGE HISTORY
Version Date Responsible Change Description
(dd/mm/yyyy)
0.10 15/06/2018 Aitor Darriba Initial Version

INTERNAL DISTRIBUTION LIST

Name e-mail Department Document Status

C Naming & Style GuideLines 2/19 Version 0.1

 C NAMING & STYLE GUIDELINES

DATE AND
NAME RESPONSIBILITY
SIGNATURE
Written by Aitor Darriba Developer 15/06/2018

Reviewed by dd/mm/yyyy

Approved by dd/mm/yyyy

Comments

Status Draft

C Naming & Style GuideLines 3/19 Version 0.1

 C NAMING & STYLE GUIDELINES

Table of Contents
1 Introduction ............................................................................................................... 6
1.1 Purpose ........................................................................................................................ 6
1.2 Scope ............................................................................................................................ 6
1.3 Definitions, acronyms and abbreviations................................................................. 6
1.4 Reference Documents ................................................................................................ 6
2 Guidelines................................................................................................................... 7
2.1 Files .............................................................................................................................. 7
2.1.1 Editor Settings ............................................................................................................. 7
2.1.2 File Extensions ............................................................................................................ 7
2.1.3 File Naming................................................................................................................. 8
2.1.4 File Templates ............................................................................................................. 8
2.2 Source Content ........................................................................................................... 9
2.2.1 Global Naming ............................................................................................................ 9
2.2.2 Includes ..................................................................................................................... 10
2.2.3 Defines and Macros .................................................................................................. 10
2.2.4 Typedefs .................................................................................................................... 12
2.2.5 Enums ....................................................................................................................... 12
2.2.6 Union......................................................................................................................... 12
2.2.7 Structs ....................................................................................................................... 13
2.2.8 Data ........................................................................................................................... 13
2.2.9 Functions ................................................................................................................... 13
2.2.10 Pointers...................................................................................................................... 13
2.2.11 Comments ................................................................................................................. 14
2.2.11.1 TODO Comments ................................................................................................. 14
2.2.11.2 Commenting Code ................................................................................................ 14
2.3 Layout ....................................................................................................................... 15
2.3.1 Pre-processor............................................................................................................. 15
2.3.2 Declarations and Definitions ..................................................................................... 15
2.3.3 Statements ................................................................................................................. 15
2.3.4 Assignment Statements ............................................................................................. 15
2.3.5 If Statements ............................................................................................................. 16
2.3.6 While Statements ...................................................................................................... 16
2.3.7 For Statements........................................................................................................... 16
2.3.8 Switch Statements ..................................................................................................... 16
2.3.9 Do Statements ........................................................................................................... 16
2.3.10 Matching Constructs ................................................................................................. 16
2.3.11 Functions ................................................................................................................... 17
2.3.11.1 Function Calls ....................................................................................................... 17
2.3.11.2 Function Declarations ........................................................................................... 17
2.3.12 Return Statements ..................................................................................................... 17
2.3.13 Goto Statmets ............................................................................................................ 17
2.3.14 Operators ................................................................................................................... 17
2.3.15 Commas .................................................................................................................... 17
2.3.16 Casts .......................................................................................................................... 18
2.3.17 Assert ........................................................................................................................ 18

C Naming & Style GuideLines 4/19 Version 0.1

 C NAMING & STYLE GUIDELINES

2.4 Variables Types ........................................................................................................ 19

C Naming & Style GuideLines 5/19 Version 0.1

 C NAMING & STYLE GUIDELINES

1 Introduction

1.1 Purpose

This document presents the roles and responsibilities for the project <project name >, and the
people who perform those roles.

1.2 Scope

Identify the scope of the coverage of the matter by the document, and describe inclusions,
exclusions, assumptions and/or limitations.

1.3 Definitions, acronyms and abbreviations

ABBREVIATION DESCRIPTION

GLOSSARY DESCRIPTION

1.4 Reference Documents

Reference Title Path Date Author

N/A C Body Template https://redmine2.ctag.com/dmsf/files/1325/download 18/06/2018 Aitor Darriba
N/A C Header Template https://redmine2.ctag.com/dmsf/files/1326/download 18/06/2018 Aitor Darriba
N/A SPW.doxyfile https://redmine2.ctag.com/dmsf/files/1324/download 18/06/2018 Aitor Darriba
Complete list of all documents related to the roles and responsibilities, identifying the title, reference
(if applicable), date and organization that provides each document.

C Naming & Style GuideLines 6/19 Version 0.1

 C NAMING & STYLE GUIDELINES

2 Guidelines

2.1 Files

2.1.1 Editor Settings

Rule GUI_FIL_EDIT_00

Description The maximum line length shall be 120 characters

Rule GUI_FIL_EDIT_01

Description The indentation must be performed by spaces instead of tab symbols

Correct Case Good
Example
Incorrect Case Bad
Example

Rule GUI_FIL_EDIT_02

Description Each tabulator must be integrated by 4 spaces

Correct Case
Example

Rule GUI_FIL_EDIT_03

Description The maximum file size must be 1000 lines

2.1.2 File Extensions

Rule GUI_FIL_EXTE_00
The file extension must change depending of the content, following the table:
.h Header Files
.c Source Files
Additional C code that only will be added to another Source File. For
.i
Description example a const matrix for a look up table.
.a Assembler File
.inc Assembler Include File
.ma
MakeFile
k

C Naming & Style GuideLines 7/19 Version 0.1

 C NAMING & STYLE GUIDELINES

2.1.3 File Naming

Rule GUI_FIL_NAMI_00

Description The allowed character for the file names are [a..z][0…9][_]

Rule GUI_FIL_NAMI_01

Description The maximum file name length shall be 31 characters

Rule GUI_FIL_NAMI_02

Description The name of the header to be exported must be the only the module prefix.
Correct Case PREFIX.h
Example

Rule GUI_FIL_NAMI_03
All the file names of the module must start with the prefix of the module
Description
followed by [_]
Correct Case PREFIX_xxxx.c, PREFIX_xxxx.h, PREFIX_xxxx.i, …
Example

2.1.4 File Templates

Rule GUI_FIL_TEMP_00
The source code files must be based on the C Body Template (check Reference
Description
Documents)

Rule GUI_FIL_TEMP_00
The header files must be based on the C Header Template (check Reference
Description
Documents)

Rule GUI_FIL_TEMP_00
The C Header Template and the C Body Template must be used with the
Description
SPW.doxyfile Doxfile (check Reference Documents)

C Naming & Style GuideLines 8/19 Version 0.1

 C NAMING & STYLE GUIDELINES

2.2 Source Content

2.2.1 Global Naming

Rule GUI_SCO_NAMI_00

Description Every module has a unique prefix chosen internally in each project

Rule GUI_SCO_NAMI_01

Description The module prefix shall has a length of exactly 4 characters

Correct Case AHAL, AMAN, …
Example

Rule GUI_SCO_NAMI_02

Description The module prefix shall not content numbers

Rule GUI_SCO_NAMI_03
The names on the code (variables, function, etc) must been descriptive in way
Description that make easy understanding its functionality and increase the readability of the
code

Rule GUI_SCO_NAMI_04
The names on the code (variables, function, etc) must been descriptive in way
Description that make easy understanding its functionality and increase the readability of the
code

Rule GUI_SCO_NAMI_05

Description The maximum length of the names on the code must be 31 characters

Rule GUI_SCO_NAMI_05
The use of literal values must be avoided (magic numbers) expressed as number
Description
itself or as number
Incorrect Case ONE, THIRD, ZERO, 65536, 0, …
Example

C Naming & Style GuideLines 9/19 Version 0.1

 C NAMING & STYLE GUIDELINES

2.2.2 Includes

Rule GUI_SCO_INCL_00

Description The local includes must been added using [“”]

Correct Case #include “local.h”
Example

Rule GUI_SCO_INCL_01

Description The external includes (libraries, compiler, etc) must been added using [<>]
Correct Case #include <external.h>
Example

Rule GUI_SCO_INCL_02

Description All includes must be placed on each specific section of the templates

Rule GUI_SCO_INCL_03
The names of the templates must match exactly with the name of the file that
Description
links also the capital letters and underscore symbols in case that exist
Correct Case #include “AHAL_file.h”
Example

Rule GUI_SCO_INCL_04

Description The public include to be exported of each shall be named with the prefix module.
Correct Case AHAL.h, AMAN.h, COMM.h
Example

2.2.3 Defines and Macros

Rule GUI_SCO_MACR_00

Description All defines and macros must be placed on each specific section of the templates.

Rule GUI_SCO_MACR_01

Description All the names must be explicit and descriptive avoiding literal names.
Correct Case BUFFER_INITIALIZATION 0, STEP_INCREMENT 1
Example
Incorrect Case ONE 1, THIRD 3, ZERO 0
Example

C Naming & Style GuideLines 10/19 Version 0.1

 C NAMING & STYLE GUIDELINES

Rule GUI_SCO_MACR_02

Description All the names must be explicit and descriptive avoiding literal names.
Correct Case BUFFER_INITIALIZATION 0, STEP_INCREMENT 1
Example
Incorrect Case ONE 1, THIRD 3, ZERO 0
Example

Rule GUI_SCO_MACR_03
The names for Global macros and defines must be the prefix of the module in
capital letters followed by the desired name in capital letter as well using
Description
underscores to separate each word following the pattern:
PREFIX_MACRO_NAME
Correct Case AHAL_BUFFER_INITIALIZATION 0, AMAN_STEP_INCREMENT 1
Example
Incorrect Case Ahal_bufferInit, STEP_INCREMENT
Example

Rule GUI_SCO_MACR_04
The names for local macros and defines must be the desired name in capital
Description letter using underscores to separate each word. Following the pattern:
MACRO_NAME
Correct Case BUFFER_INITIALIZATION 0, STEP_INCREMENT 1
Example
Incorrect Case bufferInit, STEPINCREMENT
Example

Rule GUI_SCO_MACR_05
A number that needs more that 16 bits (65536) are being used the letter L should
Description
be attached to the number to indicate to the compiler that is a Long number
Correct Case //A long integer has the L suffix
Example #define CLI_1 (65536L);

Rule GUI_SCO_MACR_06
A define that stores an unsigned number shall be declared explicitly adding the
Description
suffix U to the number
//A signed integer has no suffix
#define CI_1 (3);
Correct Case //An unsigned integer has the U suffix
Example #define CUI_1 (3U);
//A long unsigned integer has the UL suffix
#define CLUI_1 (3UL);

C Naming & Style GuideLines 11/19 Version 0.1

 C NAMING & STYLE GUIDELINES

Rule GUI_SCO_MACR_06
When a define store a negative number or an expression the parentheses ( )
Description
must be used.
//A signed integer has no suffix
#define CI_1 (3);
Correct Case //An unsigned integer has the U suffix
Example #define CUI_1 (3U);
//A long unsigned integer has the UL suffix
#define CLUI_1 (3UL);

• Los defines deben ir en la sección correspondientes de los templates

• Si el valor unsigned añadir U al valor numérico.
• Cuando se definan números negativos o expresiones se deben usar paréntesis
• Si se emplean funciones con parámetros cada parámetro en la definición debe estar dentro
de paréntesis.

2.2.4 Typedefs

• Los typedefs deben ir en su zona correspondiente del template

• Naming Global: PREFIX_<nombre_typedef>_t
• Naming Local: <nombre_typedef>_t

2.2.5 Enums

• Los enumerados deben ir en su zona correspondiente del template

• Naming Global: PREFIX_<nombre_enum>_e
• Naming local: <nombre_enum>_e
• Evitar la declaración de los enumerados como typedefs
• Los campos de los enumerados publicos serán tal que:
PREFIX_<NOMBRE_CAMPO_ENUMERADO>
• Los campos de los enumerados locales serán tal que: <NOMBRE_CAMPO_ENUMERADO>

2.2.6 Union

• Los unions deben ir en su zona correspondiente del template

• Naming Global: PREFIX_<nombre_union>_u
• Naming Local: <nombre_union>_u
• Evitar la declaración de los union como typedefs
• Los campos de los union serán tal que: <nombre_campo_union>

C Naming & Style GuideLines 12/19 Version 0.1

 C NAMING & STYLE GUIDELINES

2.2.7 Structs

• Los typedefs deben ir en su zona correspondiente del template

• Naming Global: PREFIX_<nombre_struct>_s
• Naming Local: <nombre_struct>_s
• Evitar la declaración de los struct como typedefs
• Los campos de los structs serán tal que: <nombre_campo_struct>

2.2.8 Data

• La definición y declaración de variables públicas y locales deben ir en sus zonas

correspondientes del template
• Naming Globals: PREFIX _<nombre_variable>
• Naming Locals File Scope: prefix_<nombre_variable>
• Naming Locals function Scope: <nombre_variable>
• Si la variable puede ser modificada por hardware externo o por un multiples contextos (como
interrupciones) debe ser declarada como volatile.
• Se prefiere varibles unsigned frente a signed
• Tratar de reducir el scope de las variables al minimo necesario

2.2.9 Functions

• La definición y declaración de funciones públicas y locales deben ir en sus zonas

correspondientes del template
• Naming globals: PREFIX_<NombreFuncion>
• Naming Locals: <NombreFuncion> UpperCamelCase
• Naming argumentos: typedef_t <nombre_argumento>
• Ej: OHAL_CpuSetVar(uint8_t FirstParameter);
•

2.2.10 Pointers

• El indicador de puntero debe ir acoplado a la definición del tipo y no al nombre de la

variable/parámetro.
• La definición del puntero siempre ha de ser la más restrictiva posible.
• Si la información a la que se apunta nunca va a ser modificada deben ser declarados como
const
• Si el propio valor del puntero tampoco va a ser modificado hacer este a su vez constante
• Si el valor del puntero puede ser modificado en un cambio de contexto declararlo volatile

C Naming & Style GuideLines 13/19 Version 0.1

 C NAMING & STYLE GUIDELINES

• Si la información apuntada por el puntero puede ser modificada en un cambio de contexto

marcarla como volatile. Es perfectamente posible tener punteros constantes apuntando a
datos volatile
•

2.2.11 Comments

• Comentarios simples C Style /* [Comment] */

• Comentarios doxygen /** [Comment] */
• Comentarios Doxygen Inline /**< [Comment] */
• Explicación de los campos dentro de los comentarios doxygen
• Deben seguir la estructura del template
• Los comentarios deben estar al mismo nivel de indentado que ele lemento que comenten.
• En la medida de lo posible intentar evitar entrelazar codigo y comentarios. Es preferible una
explicación detallada al inicio del bloque. Que muchas explicaciones cortas distribuidas.
• Los comentarios inline concisos y útiles.
• Los comentarios deben ser en ingles.
• En los comentarios multilena inline a la izquierda del código cada línea debe ser
independiente para evitar que alguien pueda romper el comentario al introducir líneas
intermedias que producirían efectos no esperados.

2.2.11.1 TODO Comments

• El formato para los comentarios de TODO será de la forma

/*TODO:apodousuario:AAAAMMDD:<Texto del comentario>*/

2.2.11.2 Commenting Code

• El código no debe ser comentado mediante los signos habituales. Si es necesario comentar
bloques de código se utilizara las expresión de pre-compilación #if0 #endif para delimitar el
código comentado.
• En el código de producción no debe existir código comentado.

C Naming & Style GuideLines 14/19 Version 0.1

 C NAMING & STYLE GUIDELINES

2.3 Layout

2.3.1 Pre-processor

• La compilación condicionada debe ser evitada excepto para para el caso de entorno de
simulación, multiples arquitecturas, test de integración
• Todos los header deben incluir guardas para evitar la inclusión multiple. Consultar template
• Codigo condicionado dentro de una función de be seguir respetando el identado de la
función. Pero la instrucción de precompilacón no.
• Cuando se añadan conompilaciones condicionales comprarbar macros definidas no
assignacion de valores (#ifdef si, #if no)
• La instroccion de preporcoessdor #error debería ser usada para detectar configuraciones
incorrectas del setup de configuración. (versiones incorrectas o configuraciones necesarias
no favcilitadas, por ejmplo)
• El comando #if sizeof() no se puede emplear puesto que no es portable

2.3.2 Declarations and Definitions

• Cada variable debe ser declarada en una única línea. La declaración múltiple en la misma
línea debe evitarse.
• Si existen varias líneas juntas de declaración de variables los nombres de estas debe ir
alineadas en la misma columna.
• Si existen inicialización de variables en varias líneas juntas los operadores = deben estar
alineados en la misma columna

2.3.3 Statements

• No se debe usar más que un comando por línea (a excepción del bucle for) puesto que
muchos debuggers y herramientas de analisis de coevertura funcionan con una aproximación
línea a línea.

2.3.4 Assignment Statements

• Si aparecen varias operaciones de igualado en lineas consecutives los operados de igualdad

deben estar alineados en la misma columna

C Naming & Style GuideLines 15/19 Version 0.1

 C NAMING & STYLE GUIDELINES

2.3.5 If Statements

• Todos los cuerpos de cada una de las secciones del If deben ir contenidos dentro de llaves
(compound statement). No se admite la declaración del comando en la misma línea de la
declaración del if o a continuación directa sin llaves.
• Si se emplea la estructura encadenada de else if es obligatorio la inclusión final de un else
que marque el fin del árbol de condiciones. Si este no es necesario se ha de incluir un
assert(false) dentro del mismo.
• Si solo existe un if y no es necesario el uso de un else no es necesario añadirlo.
• Para condiciones anidadas muy grandes de las condiciones if se intentar usar una
combinación de indetado y nuevas líneas tal que facilite la comprensión de cómo se unen las
expresiones and e if por lo general alineando los operados OR y AND del mismo nivel de
profundidad.
• En la medida de lo posible intentar evitar una profundidad mayor de 4 if anidados.

2.3.6 While Statements

• Todas las estructuras while deben poseer un bloque de codigo (compound statement), es
decir codigo contenido entre llaves

2.3.7 For Statements

• El cuerpo del bucle for debe ser un compound statement (un bloque de codigo entre llaves).
• La variable de control del bucle no debe ser modificada, complica la comprensión del código.
En caso de necesitar estructuras de control más complejas es preferible utilizar un while.

2.3.8 Switch Statements

• La etiqueta default debe estar siempre presente y debe tenderse a utilizarlo únicamente
para el uso de un assert(FALSE)
• El uso de case fall through debe ser evitado en la medida de la posible. Y en caso de no
quedar más remedio quedar extensa y claramente indicado. Mediante los comentarios
apropiados en la documentación y el código.

2.3.9 Do Statements

• Todo el código del bucle do debe estar contenido entre llaves

2.3.10 Matching Constructs

• Cuando se empleen patrones con un a entrada y un fin delimitados, tales como una zona
donde se desactiven las interrupcions o una zona donde se bloquea un semáforo emplear un

C Naming & Style GuideLines 16/19 Version 0.1

 C NAMING & STYLE GUIDELINES

conjunto de llaves para delimitar el bloque de código de scope limitado de modo que quede
manifiesto que el código se está ejecutando en un contexto muy específico y que una
interrupción descontrolado del mismo o una alteración si terminarlo de modo controlado
puede tener efectos no esperados

2.3.11 Functions

• El tamaño maximo de lineas por función debería ser de 100.

2.3.11.1 Function Calls

• Si el tamaño de los argumentos excede el tamaño máximo de línea permitido. Cada

argumento será situado en una nueva línea y estos alineados entre sí.
• El orden de los parámetros debe ser parámetros de entrada, luego parámetros de salida para
finalazar con parámetros de tamaño de las entradas ( al estilo del memcopy)
• Intentar mantener el número de parámetros de las funciones a cinco o menos. Más suele
indicar problemas en el particionado.

2.3.11.2 Function Declarations

• Argumentos de entrada que sean pasados como punteros pero que no sean alterados
durante la ejecución de la función deben ser declarados como const.

2.3.12 Return Statements

• El return de la función debe ser único evitando en la medida de lo posible el uso de

instrucciones tales como break o exit

2.3.13 Goto Statements

• El uso de las instrucciones goto debe evitarse siempre que sea posible. En caso de utilizarse
debe explicarse profusamente su necesidad y funcionamiento tanto en el propio código
(punto de salto y destino) como en la documentación asociada.

2.3.14 Operators

• Los operadores deben tener un espacio antes y después que permita diferenciarlos
claramente.

2.3.15 Commas

• Las comas deben ir siempre pegadas al elemento previo y antes de un espacio.

C Naming & Style GuideLines 17/19 Version 0.1

 C NAMING & STYLE GUIDELINES

2.3.16 Casts

• Todos los casts deben estar separados por un espacio de la expresión a la que hagan
referencia

2.3.17 Assert

• El uso de asserts está recomendado como segundo nivel de detección de errores. Mediante
la evaluación de pre-condiciones (como punteros nulos) y post-condiciones (como estados
inrextintes etc. Permiten una detección temprana de bugs y side effects no contemplados.

C Naming & Style GuideLines 18/19 Version 0.1

 C NAMING & STYLE GUIDELINES

2.4 Variables Types

• Se empleara los tipos base definidos en la librería stdint.h

o int8_t
int16_t
int32_t
uint8_t
uint16_t
uint32_t
• El uso de los tipos base int, short, long deben evitarse por problemas de portabilidad

C Naming & Style GuideLines 19/19 Version 0.1