C Coding Convention

Naming convention and programming style

TABLE OF CONTENTS
1. Introduction ....................................................................................................................................................................................... 3
1.1. Purpose ....................................................................................................................................................................................... 3
1.2. Definitions and Abbreviations............................................................................................................................................ 3
1.3. References.................................................................................................................................................................................. 3
2. Program structure ........................................................................................................................................................................... 3
2.1. Project organization ............................................................................................................................................................... 3
2.2. Header file structure .............................................................................................................................................................. 4
2.3. Source file structure ............................................................................................................................................................... 5
3. Naming convention ........................................................................................................................................................................ 7
3.1. General recommendations .................................................................................................................................................. 7
3.2. Files ............................................................................................................................................................................................... 7
3.3. Variables ..................................................................................................................................................................................... 7
3.4. Types ............................................................................................................................................................................................ 8
3.5. Marcos ......................................................................................................................................................................................... 9
3.6. Functions .................................................................................................................................................................................... 9
4. Source formatting ........................................................................................................................................................................... 9
4.1. Indentation ................................................................................................................................................................................ 9
4.2. Spaces ....................................................................................................................................................................................... 10
4.3. Comments ............................................................................................................................................................................... 10
4.4. Long lines ................................................................................................................................................................................ 11
4.5. Control flow statements .................................................................................................................................................... 11
4.6. Function prototypes and function implementations ............................................................................................. 11
4.7. Example .................................................................................................................................................................................... 12
5. Custom type definitions ............................................................................................................................................................ 15
5.1. Standard data types ............................................................................................................................................................ 15
5.2. Structure data type .............................................................................................................................................................. 15
6. Appendix.......................................................................................................................................................................................... 15

Page 2 of 15

1. Introduction
1.1. Purpose
This document provides guidance on selecting appropriate identifiers for elements as well as a
general structure for source files writing in the C programming language.
For consistency throughout your code and improved maintainability, you should consider using
these conventions consistently throughout your code.

1.2. Definitions and Abbreviations

Definition / Abbreviation

Description

Note

1.3. References
List all reference documents such as related processes or check lists
Number

Document title / Link

2. Program structure
2.1. Project organization
A standard firmware project should be organized as below:
Mt d n firmware chun c th c t chc nh di.
<PROJECT NAME>
CONFIG

Page 3 of 15

UTILS
SOFTWARE_FRAMEWORK
DRIVERS
<MODULE 1>

<MODULE N>
SERVICES
<SERVICE 1>

<SERVICE M>
main.c
Folder CONFIG cha cc header file c s dng cu hnh cho h thng
Folder UTILS cha cc file header v source chung.
Folder driver cha cc module c bit ging nh USB, ADC, SPI
Folder SERCICES cha cc hm API
Note: You should place related source files and header files in the same folder.

2.2. Header file structure

u cc file header, cn cung cp cc thng tin c bn v ngi lp trnh(authors), ngy to
Cu trc chung ca 1 file header
The proposed structure for a header file is as below:
/********************************************************************************
<Copyright Notice>
Product: <Product Name>
Module: <Module Name>
Version: <Version>
Author: <Author Name>
Created: <Creation Date>
Modified:
<Name>
<Date>
<Change>
Released: <Date>
Description: <Description>

Page 4 of 15

Note: <Note>
********************************************************************************/
#ifndef <FILE_DESCRIPTOR>
#define <FILE_DESCRIPTOR>
/*-----------------------------------------------------------------------------*/
/* Header inclusions
*/
/*-----------------------------------------------------------------------------*/
/*-----------------------------------------------------------------------------*/
/* Data type definitions
*/
/*-----------------------------------------------------------------------------*/
/*-----------------------------------------------------------------------------*/
/* Constant definitions
*/
/*-----------------------------------------------------------------------------*/
/*-----------------------------------------------------------------------------*/
/* Macro definitions
*/
/*-----------------------------------------------------------------------------*/
/*-----------------------------------------------------------------------------*/
/* Global variables
*/
/*-----------------------------------------------------------------------------*/
/*-----------------------------------------------------------------------------*/
/* Function prototypes
*/
/*-----------------------------------------------------------------------------*/
#endif // <FILE_DESCRIPTOR>

Recommendations
Do NOT include any other header files in the header file except general purpose header files.
You can include them in the source file that uses the header instead.
Parameters in function prototypes should have full name, so that developers can easily learn
and use these functions.
The outer file description macro must be defined in order to prevent multiple definitions. It is
named based on the module name with some underscores. The form of this macro name is
__<MODULE_NAME>_H__ where <MODULE_NAME> is the module name in upper case.
Be sure to use the correct date format (DD-MMM-YY) and the developers full name in file
headers.

2.3. Source file structure

At the beginning of a source file, you should provide a brief description of the file that contains
some basic information such as authors, creation date etc.
u ca 1 source file, phi cung cp nhng thng tin c bn m t v file nh ngi to,
ngy to
Propose source file structure
/********************************************************************************
<Copyright Notice>
Product: <Product Name>

Page 5 of 15

Module: <Module Name>

Version: <Version>
Author: <Author Name>
Created: <Creation Date>
Modified:
<Name>
<Date>
<Change>
Released: <Date>
Description: <Description>
Note: <Note>
********************************************************************************/
/*-----------------------------------------------------------------------------*/
/* Header inclusions
*/
/*-----------------------------------------------------------------------------*/
/*-----------------------------------------------------------------------------*/
/* Local Constant definitions
*/
/*-----------------------------------------------------------------------------*/
/*-----------------------------------------------------------------------------*/
/* Local Macro definitions
*/
/*-----------------------------------------------------------------------------*/
/*-----------------------------------------------------------------------------*/
/* Local Data type definitions
*/
/*-----------------------------------------------------------------------------*/
/*-----------------------------------------------------------------------------*/
/* Global variables
*/
/*-----------------------------------------------------------------------------*/
/*-----------------------------------------------------------------------------*/
/* Function prototypes
*/
/*-----------------------------------------------------------------------------*/
/*-----------------------------------------------------------------------------*/
/* Function implementations
*/
/*-----------------------------------------------------------------------------*/

Recommendations
Reduce using global variables as few as possible. It is recommended that you define global
variables in a separated source file.
Parameters in function implementation headers should have the same name as parameters
in function prototypes.

Page 6 of 15

3. Naming convention
3.1. General recommendations
Tt c tn, comment, m t phi c thc hin bng ting anh.
Chn cch d hiu nht t tn

3.2. Files
Tn source files v header file phi t bng ch in thng.
Tn file khng c cha nhiu hn 1 du ..
Tn file khng c qu 8 k t, v 3 k t m rng.

3.3. Variables
y l hng dn t tn bin theo chun Hungari. N c nh ngha cc tin t cho cc tn
bin.
Data type prefix

Description

Natural number

Integer number

Unsigned integer number

32 bits long integer number

bi

Bit

by

Byte

16 bits unsigned integer number (word)

dw

Double words

Boolean

Character

Pointer

lp

Long pointer

ifp

Pointer to internal flash memories

efp

Pointer to external flash memories

Page 7 of 15

irp Pointer to internal

external RAMs sz

RAMs erp Pointer to

Null-terminated string

psz Pointer to a nulla null-terminated

terminated string lpsz Long pointer to

string

ar Array bf Buffer h
Handle
str String regardless

of type

st Structure em
Enumeration
un Union
The type of a variable
member variable.

is used to indicate that it is a global variable, a static variable, or a class

Local non-static variables do not have the type prefix.

Variable type prefix

Description

g_

Global variable

s_

Static variable

m_
Class member variable
The name part can contains one or more words. The first letter of each word in the name part is
capitalized.
For example:
szUserName: Mt user name l 1 xu kt thc bng zero
lpszPath: L mt con tr Path , c tr vo xu c kt thc bng zero
g_pData: L 1 con tr ton cc tr vo block data
Note: Some popular variables may not follow this convention.
For example:
Variables

Description

i, j, k, l, m, n, x, y, z

Using for counting purpose.

Char variable

String variable

3.4. Types
Ngi lp trnh c th nh ngha kiu d liu mi thng qua t kha typedef. Tt c cc k t
ca n phi c vit hoa v khng c space hoc gch di.
For example:
DWORD: a double word data type

Page 8 of 15

Version 1.0
LPSTR: a long pointer string data type
DEVICEINFO: a structure contains information about a device

3.5. Marcos
Tt c cc k t khi nh ngha macros phi c vit hoa v ngn cch cc t bng k t _
For example:
#define DEV_MEMORY 1500
#define GET_ITEM(p, l, c, w) ((p) + (l)*(w) + (c))

Some popular modules:

Prefix

Module

ZB_

ZigBee

PLC_

PLC

LCD_

LCD

RTC_

Real-time clock

USB_

Universal Serial Bus

3.6. Functions
The first letter in the identifier and the first letter of each subsequent concatenated word are
capitalized.
K t u tin ca t c vit hoa.
trnh conflicts th c th them tn module vo u tn hm <Module name>_<Function
name>.
Tn hm thng thc hin 1 tc v nn thng gm 1 ng t i tip theo l 1 danh t.
For example:
DisplayString(LPSTR lpszMessage)
Usart_SendBytes(LPBYTE lpBuffer)
GetDateFromDB()
ZB_SendData()

Cc hm callback phi c hu t Proc hoc Func ph sau

For example:
ThreadProc()
ReceiveFunc()

4. Source formatting
4.1. Indentation
Sa dng 1 tab hoc 4 space cho cch khi lnh dng lnh cho tng level

Page 9 of 15

Version 1.0
Nhng i tng phi t u tin trong file source:
-

Preprocessors

Global type definitions

Function prototypes

Function implementations

Phn body ca while, for, if phi li vo 1 level.

4.2. Spaces
Spaces c s dng sau:
-

Cho cc ton t, ton hng.

Sau vng if, while, for, switch, kt thc 1 khi lnh.

Pha sau du chm hoc du chm phy.

Spaces khng c s dng sau:

-

Gia tn hm v du (

Trc ( v sau ).

Trc du chm hoc du chm phy.

4.3. Comments
Trong ANSI C tt c ch thch c t trong /* v */ cn // khng phi l ANSI v khng
c h tr trn tt c cc trnh bin dch.
Khi comment nn s dung quy tc thi tht theo code pha trn. c vit bng ch
thng bng ting anh. L m t ngn gn ch nng, phng thc hot ng
Dng ch thch c th c t cng dng vi macros hoc code.
For example:
#define STATE_SELECTED
#define STATE_READY
#define STATE_STARTED

0
1
2

// assigned device state

// ready for using device state
// running device state

Phn comment c th c ch thch loi nhng phn code c th c b i.

Page 10 of 15

Version 1.0

4.4. Long lines

Cc dng lnh di hn 80 k t cn c ct nh, v s dng k t \ chia nh dng lnh.
Khi dng lnh c chia nh th, cc dng lnh cn li nn tht vo 1 tab.

4.5. Control flow statements

Cc quy c c p dng cho cc cu trc ging nh if, while, for.

Nu ch c 1 cu lnh th ch cn tht vo 1 level.

Nu l 1 block, th cc lnh phi t thnh 1 ct.

4.6. Function prototypes and function implementations

Ci ny p dng cho m t nguyn mu ca tt c cc hm. Cc nguyn mu hm c miu
t trong cc file header hoc u cu cc file source m hm c nh ngha.

Nguyn mu hm v tiu ca hm phi ng nht.

Phn m u ca thn hm phi t trn 1 dng mi.

M t ngn gn v cung cp thng tin v chc nng, nguyn mu hm, tham s
/*------------------------------------------------------------------------------Function: <Function prototype>
Purpose: <Purpose>
Parameters: <Parameter list>
Return: <Return value>
Comments: <Any addition comments>
Modified:
<Modified by>
<Date>
<Change>
-------------------------------------------------------------------------------*/

Page 11 of 15

Version 1.0

4.7. Example
/********************************************************************************
Copyright (C) 2014 - 2016 DangNQ . All rights reserved.
Product: EXAMPLE
Module: uart.c
Version: 1.0
Author: Nguyen Quoc Dang
Created: 29-Sep-08
Modified:
<Name>
<Date>
<Change>
Released: 01-Oct-08
Description: Including functions for UART communication
Note: <Note>
********************************************************************************/
/*-----------------------------------------------------------------------------*/
/* Header inclusions
*/
/*-----------------------------------------------------------------------------*/
#include <string.h>
#include <uart.h>
/*-----------------------------------------------------------------------------*/
/* Local Data type definitions
*/
/*-----------------------------------------------------------------------------*/
/*-----------------------------------------------------------------------------*/
/* Local Constant definitions
*/
/*-----------------------------------------------------------------------------*/
/*-----------------------------------------------------------------------------*/
/* Local Macro definitions
*/
/*-----------------------------------------------------------------------------*/
/*-----------------------------------------------------------------------------*/
/* Global variables
*/
/*-----------------------------------------------------------------------------*/
/*-----------------------------------------------------------------------------*/
/* Function prototypes
*/

Page 12 of 15

Version 1.0
/*-----------------------------------------------------------------------------*/
/*-----------------------------------------------------------------------------*/
/* Function implementations
*/ /*----------------------------------------------------------------------------*/
/*------------------------------------------------------------------------------Function: void Uart_SetBaudrate(USHORT uSpeed);
Purpose: Set baudrate speed for serial communication.
Parameters: uSpeed
Return: none
Comments: The baudrate speed depends on frequency of crystal.
This project uses 11.0592 MHz crystal
Modified:
<Modified by>
<Date>
<Change>
--------------------------------------------------------------------------------*/
void Uart_SetBaudrate(USHORT uSpeed)
{
switch (uSpeed)
{
case 9600:
{
TH1 = LOBYTE(-3);
break;
}
case 4800:
{
TH1 = LOBYTE(-6);
break;
}
case 2400:
{
TH1
= LOBYTE(-12);
break;
}
}
TR1 = ON;
}
/*------------------------------------------------------------------------------Function: void Uart_Transmit(PSTR pszTransmit);
Purpose: Transmit a string via serial communication
Parameters: pszTransmit
Return: none
Comments: <Any addition comments>
Modified:

Page 13 of 15

Version 1.0
<Modified by>
<Date>
<Change>
-------------------------------------------------------------------------------*/
void Uart_Transmit(PSTR pszTransmit)
{
BYTE nCount, nLength;
nLength = strlen(pszTransmit);

Page 14 of 15

Version 1.0
for (nCount = 0; nCount < nLength; nCount++)
{
TI = OFF;
SBUF = pszTransmit[nCount];
while (TI == OFF);
TI = OFF;

}
}

5. Custom type definitions

5.1. Standard data types
Chng ta nn s dng mt s kiu d liu nh lit k di.
Integer data types: BYTE, SHORT, INT, LONG, USHORT, UINT, ULONG, WORD, DWORD
Float data types: FLOAT, DOUBLE
Character data type: CHAR
Logical data type: BOOL
Void data type: VOID
Pointer data type: P<Type>, LP<Type>
String pointer data type: PSTR, LPSTR

5.2. Structure data type

Khi nh ngha 1 cu trc th cn nh ngha kiu cu trc v kiu con tr cu trc.
For example:
typedef struct tagPOINT
{
INT x, y;
} POINT, *PPOINT;

6. Appendix

Page 15 of 15