github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-08-03 09:23:35 +00:00
Code Issues Projects Releases Wiki Activity

doc: add more rules in coding guidelines

Browse Source 
This patch adds more rules in coding guidelines.

Tracked-On: #861
Signed-off-by: Shiqing Gao <shiqing.gao@intel.com>
This commit is contained in:
Shiqing Gao 2019-01-18 17:10:37 +08:00 committed by David Kinder
parent 3c60512738
commit d0c9fce72d
1 changed files with 613 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

613
doc/developer-guides/coding_guidelines.rst
View File

@ -37,6 +37,51 @@ Compliant example::
printf("%d \n", CONCAT(a, b, c)); printf("%d \n", CONCAT(a, b, c));
PP-02: Function-like MACRO shall be used with restrictions
==========================================================
Function-like MACRO shall be replaced with inline function if it is possible.
Compliant example::
static inline uint32_t func_showcase(uint32_t a, uint32_t b)
{
return a + b;
}
.. rst-class:: non-compliant-code
Non-compliant example::
#define SHOWCASE(a, b) ((a) + (b))
PP-03: Header file shall not be included multiple times
=======================================================
The content inside shall be protected with #ifndef, #if !defined, or #ifdef.
Compliant example::
/* In `showcase.h`: */
#ifndef SHOWCASE_H
#define SHOWCASE_H
/* header contents */
uint32_t func_showcase(uint32_t param);
#endif /* SHOWCASE_H */
.. rst-class:: non-compliant-code
Non-compliant example::
/* In `showcase.h`: */
/* header contents without any protection */
uint32_t func_showcase(uint32_t param);
Compilation Units Compilation Units
***************** *****************
@ -348,6 +393,20 @@ Compliant example::
} }
DI-07: An array shall be fully initialized
==========================================
Compliant example::
uint32_t showcase_array[5] = {0, 1, 2, 3, 4};
.. rst-class:: non-compliant-code
Non-compliant example::
uint32_t showcase_array[5] = {0, 1};
Functions Functions
********* *********
@ -535,6 +594,72 @@ Compliant example::
} }
FN-08: All static functions shall be used within the file they are declared
===========================================================================
Unlike global functions in C, access to a static function is restricted to the
file where it is declared. Therefore, a static function shall be used in the
file where it is declared, either called explicitly or indirectly via its
address. Otherwise, the static function shall be removed.
Compliant example::
static void func_showcase(uint32_t param)
{
printf("param %d \n", param);
}
void main(void)
{
func_showcase(10U);
}
.. rst-class:: non-compliant-code
Non-compliant example::
/* func_showcase is not called explicitly or accessed via the address */
static void func_showcase(uint32_t param)
{
printf("param %d \n", param);
}
FN-09: The formal parameter name of a function shall be consistent
==================================================================
The formal parameter name of a function shall be the same between its
declaration and definition.
Compliant example::
/* In `showcase.h`: */
uint32_t func_showcase(uint32_t param);
/* In `showcase.c`: */
#include "showcase.h"
uint32_t func_showcase(uint32_t param)
{
return param;
}
.. rst-class:: non-compliant-code
Non-compliant example::
/* In `showcase.h`: */
uint32_t func_showcase(uint32_t param);
/* In `showcase.c`: */
#include "showcase.h"
uint32_t func_showcase(uint32_t param_1)
{
return param_1;
}
Statements Statements
********** **********
@ -915,6 +1040,190 @@ Compliant example::
showcase=showcase*2U; showcase=showcase*2U;
ST-17: Infinite loop shall not exist
====================================
Every path in the iteration loop shall have the chance to exit.
Compliant example::
uint32_t count = 10U;
bool showcase_flag = false;
while (count > 5U)
{
if (showcase_flag) {
count--;
} else {
count = count - 2U;
}
}
.. rst-class:: non-compliant-code
Non-compliant example::
uint32_t count = 10U;
bool showcase_flag = false;
while (count > 5U)
{
if (showcase_flag) {
count--;
}
}
ST-18: ++ or -- operation shall be used with restrictions
==========================================================
Only the following cases shall be allowed:
a) ++ or -- operation shall be allowed if it is used alone in the expression;
b) ++ or -- operation shall be allowed if it is used as the third expression of
a for loop.
Compliant example::
uint32_t showcase = 0U;
showcase++;
.. rst-class:: non-compliant-code
Non-compliant example::
uint32_t showcase = 0U;
uint32_t showcase_test;
showcase_test = showcase++;
Expressions
***********
EP-01: The initialization expression of a for loop shall be simple
==================================================================
The initialization expression of a for loop shall only be used to initialize the
loop counter. All other operations shall not be allowed.
Compliant example::
uint32_t i;
for (i = 0U; i < 5U; i++) {
printf("count: %d \n", i);
}
.. rst-class:: non-compliant-code
Non-compliant example::
uint32_t i;
uint32_t showcase = 0U;
for (i = 0U, showcase = 10U; i < 5U; i++) {
printf("count: %d \n", i);
}
EP-02: The controlling expression of a for loop shall not be empty
==================================================================
Compliant example::
uint32_t i;
for (i = 0U; i < 5U; i++) {
printf("count: %d \n", i);
}
.. rst-class:: non-compliant-code
Non-compliant example::
uint32_t i;
for (i = 0U; ; i++) {
printf("count: %d \n", i);
if (i > 4U) {
break;
}
}
EP-03: The third expression of a for loop shall be simple
=========================================================
The third expression of a for loop shall only be used to increase or decrease
the loop counter with the following operators, ++, --, +=, or -=. All other
operations shall not be allowed.
Compliant example::
uint32_t i;
for (i = 0U; i < 5U; i++) {
printf("count: %d \n", i);
}
.. rst-class:: non-compliant-code
Non-compliant example::
uint32_t i;
uint32_t showcase = 0U;
for (i = 0U; i < 5U; i++, showcase++) {
printf("count: %d \n", i);
}
EP-04: The evaluation order of an expression shall not influence the result
===========================================================================
Compliant example::
uint32_t showcase = 0U;
uint32_t showcase_test = 10U;
showcase++;
showcase_test = showcase_test + showcase;
.. rst-class:: non-compliant-code
Non-compliant example::
uint32_t showcase = 0U;
uint32_t showcase_test = 10U;
showcase_test = showcase_test + ++showcase;
EP-05: Parentheses shall be used to set the operator precedence explicitly
==========================================================================
Compliant example::
uint32_t showcase_u32_1 = 0U;
uint32_t showcase_u32_2 = 0xFFU;
uint32_t showcase_u32_3;
showcase_u32_3 = showcase_u32_1 * (showcase_u32_2 >> 4U);
.. rst-class:: non-compliant-code
Non-compliant example::
uint32_t showcase_u32_1 = 0U;
uint32_t showcase_u32_2 = 0xFU;
uint32_t showcase_u32_3;
showcase_u32_3 = showcase_u32_1 * showcase_u32_2 >> 4U;
Types Types
***** *****
@ -1121,6 +1430,272 @@ Compliant example::
struct struct_showcase showcase = {32U, -1}; struct struct_showcase showcase = {32U, -1};
TY-09: The type used in switch statement shall be consistent
============================================================
The type shall be consistent between the case expression and the controlling
expression of switch statement.
Compliant example::
enum enum_showcase {
ENUM_SHOWCASE_0,
ENUM_SHOWCASE_1,
ENUM_SHOWCASE_2
};
enum enum_showcase showcase;
switch (showcase) {
case ENUM_SHOWCASE_0:
/* showcase */
break;
case ENUM_SHOWCASE_1:
/* showcase */
break;
default:
/* showcase */
break;
.. rst-class:: non-compliant-code
Non-compliant example::
enum enum_showcase {
ENUM_SHOWCASE_0,
ENUM_SHOWCASE_1,
ENUM_SHOWCASE_2
};
enum enum_showcase showcase;
switch (showcase) {
case ENUM_SHOWCASE_0:
/* showcase */
break;
case 1U:
/* showcase */
break;
default:
/* showcase */
break;
TY-10: const qualifier shall not be discarded in cast operation
===============================================================
Compliant example::
const uint32_t *showcase_const;
const uint32_t *showcase = showcase_const;
.. rst-class:: non-compliant-code
Non-compliant example::
const uint32_t *showcase_const;
uint32_t *showcase = (uint32_t *)showcase_const;
TY-11: A variable shall be declared as static if it is only used in the file where it is declared
=================================================================================================
Compliant example::
/* In `showcase.c`: */
/* `showcase` is only in `showcase.c` */
static uint32_t showcase;
.. rst-class:: non-compliant-code
Non-compliant example::
/* In `showcase.c`: */
/* `showcase` is only in `showcase.c` */
uint32_t showcase;
TY-12: All type conversions shall be explicit
=============================================
Implicit type conversions shall not be allowed.
Compliant example::
uint32_t showcase_u32;
uint64_t showcase_u64 = 64UL;
showcase_u32 = (uint32_t)showcase_u64;
.. rst-class:: non-compliant-code
Non-compliant example::
uint32_t showcase_u32;
uint64_t showcase_u64 = 64UL;
showcase_u32 = showcase_u64;
TY-13: Cast shall be performed on operands rather than arithmetic expressions
=============================================================================
Compliant example::
uint32_t showcase_u32_1 = 10U;
uint32_t showcase_u32_2 = 10U;
uint64_t showcase_u64;
showcase_u64 = (uint64_t)showcase_u32_1 + (uint64_t)showcase_u32_2;
.. rst-class:: non-compliant-code
Non-compliant example::
uint32_t showcase_u32_1 = 10U;
uint32_t showcase_u32_2 = 10U;
uint64_t showcase_u64;
showcase_u64 = (uint64_t)(showcase_u32_1 + showcase_u32_2);
TY-14: A complex integer expression shall not be cast to types other than integer
=================================================================================
Compliant example::
/* 0x61 is 'a' in ASCII Table */
uint32_t showcase_u32;
char showcase_char;
showcase_u32 = 0x61U + 1U;
showcase_char = (char)showcase_u32;
.. rst-class:: non-compliant-code
Non-compliant example::
/* 0x61 is 'a' in ASCII Table */
uint32_t showcase_u32;
char showcase_char;
showcase_u32 = 0x61U;
showcase_char = (char)(showcase_u32 + 1U);
TY-15: Integer shall not be used when a character is expected
=============================================================
Compliant example::
char showcase;
switch (showcase) {
case 'a':
/* do something */
break;
case 'A':
/* do something */
break;
default:
break;
}
.. rst-class:: non-compliant-code
Non-compliant example::
char showcase;
switch (showcase) {
/* 0x61 is 'a' in ASCII Table */
case 0x61:
/* do something */
break;
case 'A':
/* do something */
break;
default:
break;
}
TY-16: A pointer shall not be cast to an integer
================================================
Compliant example::
uint64_t *showcase_ptr;
uint64_t showcase = *showcase_ptr;
.. rst-class:: non-compliant-code
Non-compliant example::
uint64_t *showcase_ptr;
uint64_t showcase = (uint64_t)showcase_ptr;
TY-17: An integer shall not be cast to a pointer
================================================
Compliant example::
uint64_t showcase = 10UL;
uint64_t *showcase_ptr = &showcase;
.. rst-class:: non-compliant-code
Non-compliant example::
uint64_t showcase = 10UL;
uint64_t *showcase_ptr = (uint64_t *)showcase;
TY-18: All types declared by typedef shall be used
==================================================
Typedefs that are not used shall be deleted.
Compliant example::
typedef unsigned int uint32_t;
uint32_t showcase;
.. rst-class:: non-compliant-code
Non-compliant example::
typedef unsigned int uint32_t;
/* uint32_t_backup is not being used anywhere */
typedef unsigned int uint32_t_backup;
uint32_t showcase;
TY-19: Array indexing shall only be performed on array type
===========================================================
Compliant example::
char showcase[4] = {'s', 'h', 'o', 'w'};
char chr = showcase[1];
.. rst-class:: non-compliant-code
Non-compliant example::
char *showcase = "show";
char chr = showcase[1];
Identifiers Identifiers
*********** ***********
@ -1288,3 +1863,41 @@ Compliant example::
} }
ID-06: The typedef name shall be unique
=======================================
The typedef name shall be unique and not be used for any other purpose.
Compliant example::
typedef unsigned int uint32_t;
uint32_t showcase;
.. rst-class:: non-compliant-code
Non-compliant example::
typedef unsigned int uint32_t;
uint32_t uint32_t;
ID-07: Name defined by developers shall not start with underscore
=================================================================
All names starting with one or two underscores are reserved for use by the
compiler and standard libraries to eliminate potential conflicts with user-
defined names.
Compliant example::
uint32_t showcase;
.. rst-class:: non-compliant-code
Non-compliant example::
uint32_t __showcase;