mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-07-05 19:47:48 +00:00
doc: add some rules related to coding style
This patch adds some rules related to coding style. Tracked-On: #861 Signed-off-by: Shiqing Gao <shiqing.gao@intel.com>
This commit is contained in:
Shiqing Gao
David Kinder
parent
ff65a10391
commit
30159d5b28
470
doc/developer-guides/coding_guidelines.rst
Normal file → Executable file
470
doc/developer-guides/coding_guidelines.rst
Normal file → Executable file
@ -1332,72 +1332,7 @@ Compliant example::
|
|||||||
printf("count: %d \n", i);
|
printf("count: %d \n", i);
|
||||||
|
|
||||||
|
|
||||||
ST-14: A space shall exist between the expression and the control keywords
|
ST-14: Infinite loop shall not exist
|
||||||
==========================================================================
|
|
||||||
|
|
||||||
A space shall exist between the expression and the control keywords, including
|
|
||||||
if, switch, while, and for.
|
|
||||||
|
|
||||||
Compliant example::
|
|
||||||
|
|
||||||
uint32_t showcase;
|
|
||||||
|
|
||||||
if (showcase == 0U) {
|
|
||||||
showcase = 32U;
|
|
||||||
}
|
|
||||||
|
|
||||||
.. rst-class:: non-compliant-code
|
|
||||||
|
|
||||||
Non-compliant example::
|
|
||||||
|
|
||||||
uint32_t showcase;
|
|
||||||
|
|
||||||
if(showcase == 0U){
|
|
||||||
showcase = 32U;
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
ST-15: A space shall exist after the semicolon in a for expression
|
|
||||||
==================================================================
|
|
||||||
|
|
||||||
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 < 5U;i++) {
|
|
||||||
printf("count: %d \n", i);
|
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
ST-16: A space shall exist around binary operators and assignment operators
|
|
||||||
===========================================================================
|
|
||||||
|
|
||||||
Compliant example::
|
|
||||||
|
|
||||||
uint32_t showcase = 32U;
|
|
||||||
|
|
||||||
showcase = showcase * 2U;
|
|
||||||
|
|
||||||
.. rst-class:: non-compliant-code
|
|
||||||
|
|
||||||
Non-compliant example::
|
|
||||||
|
|
||||||
uint32_t showcase=32U;
|
|
||||||
|
|
||||||
showcase=showcase*2U;
|
|
||||||
|
|
||||||
|
|
||||||
ST-17: Infinite loop shall not exist
|
|
||||||
====================================
|
====================================
|
||||||
|
|
||||||
Every path in the iteration loop shall have the chance to exit.
|
Every path in the iteration loop shall have the chance to exit.
|
||||||
@ -1431,7 +1366,7 @@ Compliant example::
|
|||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
ST-18: ++ or -- operation shall be used with restrictions
|
ST-15: ++ or -- operation shall be used with restrictions
|
||||||
==========================================================
|
==========================================================
|
||||||
|
|
||||||
Only the following cases shall be allowed:
|
Only the following cases shall be allowed:
|
||||||
@ -1456,7 +1391,7 @@ Compliant example::
|
|||||||
showcase_test = showcase++;
|
showcase_test = showcase++;
|
||||||
|
|
||||||
|
|
||||||
ST-19: Array indexing shall be in-bounds
|
ST-16: Array indexing shall be in-bounds
|
||||||
========================================
|
========================================
|
||||||
|
|
||||||
An array index value shall be between zero (for the first element) and the array
|
An array index value shall be between zero (for the first element) and the array
|
||||||
@ -1478,7 +1413,7 @@ Compliant example::
|
|||||||
char showcase = showcase_array[10];
|
char showcase = showcase_array[10];
|
||||||
|
|
||||||
|
|
||||||
ST-20: The else statement shall not be empty if it is following an else if
|
ST-17: The else statement shall not be empty if it is following an else if
|
||||||
==========================================================================
|
==========================================================================
|
||||||
|
|
||||||
Either a non-null statement or a comment shall be included in the else
|
Either a non-null statement or a comment shall be included in the else
|
||||||
@ -1511,7 +1446,7 @@ Compliant example::
|
|||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
ST-21: A switch statement shall have the default statement
|
ST-18: A switch statement shall have the default statement
|
||||||
==========================================================
|
==========================================================
|
||||||
|
|
||||||
This is to guarantee that the developers have considered all of the possible
|
This is to guarantee that the developers have considered all of the possible
|
||||||
@ -1549,7 +1484,7 @@ Compliant example::
|
|||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
ST-22: Every switch clause shall be terminated with a break statement
|
ST-19: Every switch clause shall be terminated with a break statement
|
||||||
=====================================================================
|
=====================================================================
|
||||||
|
|
||||||
Falling through a case shall not be allowed.
|
Falling through a case shall not be allowed.
|
||||||
@ -1587,7 +1522,7 @@ Compliant example::
|
|||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
ST-23: The comma operator shall not be used
|
ST-20: The comma operator shall not be used
|
||||||
===========================================
|
===========================================
|
||||||
|
|
||||||
Compliant example::
|
Compliant example::
|
||||||
@ -1608,7 +1543,7 @@ Compliant example::
|
|||||||
showcase_a++, showcase_b++;
|
showcase_a++, showcase_b++;
|
||||||
|
|
||||||
|
|
||||||
ST-24: The for loop counter shall not be changed inside the loop body
|
ST-21: The for loop counter shall not be changed inside the loop body
|
||||||
=====================================================================
|
=====================================================================
|
||||||
|
|
||||||
Compliant example::
|
Compliant example::
|
||||||
@ -2787,3 +2722,392 @@ Compliant example::
|
|||||||
#define _Bool bool
|
#define _Bool bool
|
||||||
|
|
||||||
|
|
||||||
|
Coding Style
|
||||||
|
************
|
||||||
|
|
||||||
|
General
|
||||||
|
=======
|
||||||
|
|
||||||
|
GN-01: Each line shall contain at most 120 characters
|
||||||
|
-----------------------------------------------------
|
||||||
|
|
||||||
|
No more than 120 characters shall be on a line, with tab stops every 8
|
||||||
|
characters. Statements longer than this limit shall be broken into multiple
|
||||||
|
lines with proper alignment.
|
||||||
|
|
||||||
|
Compliant example::
|
||||||
|
|
||||||
|
cpuid(CPUID_EXTEND_FEATURE, &unused,
|
||||||
|
&boot_cpu_data.cpuid_leaves[FEAT_7_0_EBX],
|
||||||
|
&boot_cpu_data.cpuid_leaves[FEAT_7_0_ECX],
|
||||||
|
&boot_cpu_data.cpuid_leaves[FEAT_7_0_EDX]);
|
||||||
|
|
||||||
|
.. rst-class:: non-compliant-code
|
||||||
|
|
||||||
|
Non-compliant example::
|
||||||
|
|
||||||
|
cpuid(CPUID_EXTEND_FEATURE, &unused, &boot_cpu_data.cpuid_leaves[FEAT_7_0_EBX], &boot_cpu_data.cpuid_leaves[FEAT_7_0_ECX], &boot_cpu_data.cpuid_leaves[FEAT_7_0_EDX]);
|
||||||
|
|
||||||
|
|
||||||
|
GN-02: Each line shall only contain one statement
|
||||||
|
-------------------------------------------------
|
||||||
|
|
||||||
|
Compliant example::
|
||||||
|
|
||||||
|
if (condition) {
|
||||||
|
do_a();
|
||||||
|
} else {
|
||||||
|
do_b();
|
||||||
|
}
|
||||||
|
|
||||||
|
.. rst-class:: non-compliant-code
|
||||||
|
|
||||||
|
Non-compliant example::
|
||||||
|
|
||||||
|
if (condition) { do_a();} else {do_b();}
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Indentation
|
||||||
|
===========
|
||||||
|
|
||||||
|
IT-01: Tabs shall be used for code indentation
|
||||||
|
----------------------------------------------
|
||||||
|
|
||||||
|
Spaces are allowed only for indenting comments or aligning statements that span
|
||||||
|
multiple lines.
|
||||||
|
|
||||||
|
Compliant example::
|
||||||
|
|
||||||
|
if (condition) {
|
||||||
|
do_a();
|
||||||
|
} else {
|
||||||
|
do_b();
|
||||||
|
}
|
||||||
|
|
||||||
|
.. rst-class:: non-compliant-code
|
||||||
|
|
||||||
|
Non-compliant example::
|
||||||
|
|
||||||
|
if (condition) {
|
||||||
|
do_a();
|
||||||
|
} else {
|
||||||
|
do_b();
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
IT-02: Tabs shall be 8 characters wide
|
||||||
|
--------------------------------------
|
||||||
|
|
||||||
|
A tab character shall be considered 8-character wide when limiting the line
|
||||||
|
width.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Whitespaces
|
||||||
|
===========
|
||||||
|
|
||||||
|
WS-01: Trailing whitespaces shall not be allowed at the end of lines
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
|
||||||
|
This rule applies to both spaces and tabs at the end of a line.
|
||||||
|
|
||||||
|
Compliant example::
|
||||||
|
|
||||||
|
uint32_t a;
|
||||||
|
uint32_t b;
|
||||||
|
uint32_t c;
|
||||||
|
|
||||||
|
.. rst-class:: non-compliant-code
|
||||||
|
|
||||||
|
Non-compliant example::
|
||||||
|
|
||||||
|
/*
|
||||||
|
* The example here uses the char ␣ to stand for the space at the end of the line
|
||||||
|
* in order to highlight the non-compliant part.
|
||||||
|
*/
|
||||||
|
uint32_t a;␣␣␣␣
|
||||||
|
uint32_t b;␣␣␣␣
|
||||||
|
uint32_t c;␣␣␣␣
|
||||||
|
|
||||||
|
|
||||||
|
WS-02: A single space shall exist between non-function-like keywords and opening brackets
|
||||||
|
-----------------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
A single space shall exist between a non-function-like keyword and the opening
|
||||||
|
bracket (either a brace or a parenthesis) that follows. This rule applies to the
|
||||||
|
keywords 'if', 'else', 'for', 'do', 'while', 'switch' and 'return'.
|
||||||
|
|
||||||
|
Compliant example::
|
||||||
|
|
||||||
|
uint32_t showcase;
|
||||||
|
|
||||||
|
if (showcase == 0U) {
|
||||||
|
showcase = 32U;
|
||||||
|
}
|
||||||
|
|
||||||
|
.. rst-class:: non-compliant-code
|
||||||
|
|
||||||
|
Non-compliant example::
|
||||||
|
|
||||||
|
uint32_t showcase;
|
||||||
|
|
||||||
|
if(showcase == 0U){
|
||||||
|
showcase = 32U;
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
WS-03: Space shall not exist between the function identifier and the following open-parenthesis
|
||||||
|
-----------------------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
Compliant example::
|
||||||
|
|
||||||
|
size_t entry_size = sizeof(struct vcpuid_entry);
|
||||||
|
|
||||||
|
.. rst-class:: non-compliant-code
|
||||||
|
|
||||||
|
Non-compliant example::
|
||||||
|
|
||||||
|
size_t entry_size = sizeof (struct vcpuid_entry);
|
||||||
|
|
||||||
|
|
||||||
|
WS-04: Space shall not exist right after opening brackets and right before closing ones
|
||||||
|
---------------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
Brackets in this rule refer to parenthesis, braces and squared brackets.
|
||||||
|
|
||||||
|
Compliant example::
|
||||||
|
|
||||||
|
size_t entry_size = sizeof(struct vcpuid_entry);
|
||||||
|
|
||||||
|
.. rst-class:: non-compliant-code
|
||||||
|
|
||||||
|
Non-compliant example::
|
||||||
|
|
||||||
|
size_t entry_size = sizeof( struct vcpuid_entry );
|
||||||
|
|
||||||
|
|
||||||
|
WS-05: The '*' characters used for pointers shall be right before the function or variable identifiers
|
||||||
|
------------------------------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
The following cases shall be covered:
|
||||||
|
|
||||||
|
a) For declaration of variables of a pointer type, the '*' character shall be
|
||||||
|
right before the variable identifier with no space in between.
|
||||||
|
b) For functions whose return value is of a pointer type, the '*' character
|
||||||
|
shall be right before the function identifyer with no spaces in between in the
|
||||||
|
function prototype.
|
||||||
|
|
||||||
|
Compliant example::
|
||||||
|
|
||||||
|
uint32_t *showcase_ptr;
|
||||||
|
uint32_t *showcase_func(void);
|
||||||
|
|
||||||
|
.. rst-class:: non-compliant-code
|
||||||
|
|
||||||
|
Non-compliant example::
|
||||||
|
|
||||||
|
uint32_t* showcase_ptr;
|
||||||
|
uint32_t* showcase_func(void);
|
||||||
|
|
||||||
|
|
||||||
|
WS-06: A single space shall exist around binary and ternary operators
|
||||||
|
---------------------------------------------------------------------
|
||||||
|
|
||||||
|
This rule applies to all binary arithmetic, bit-wise, logical, relational,
|
||||||
|
equality and assignment operators, as well as the ternary conditional operator.
|
||||||
|
|
||||||
|
Compliant example::
|
||||||
|
|
||||||
|
uint32_t showcase = 32U;
|
||||||
|
|
||||||
|
showcase = showcase * 2U;
|
||||||
|
|
||||||
|
.. rst-class:: non-compliant-code
|
||||||
|
|
||||||
|
Non-compliant example::
|
||||||
|
|
||||||
|
uint32_t showcase=32U;
|
||||||
|
|
||||||
|
showcase=showcase*2U;
|
||||||
|
|
||||||
|
|
||||||
|
WS-07: Space shall not exist after unary operator
|
||||||
|
-------------------------------------------------
|
||||||
|
|
||||||
|
There shall be no space between a unary operator and its operand. This rule
|
||||||
|
applies to member accesses, prefix or postfix increments and decrements, address
|
||||||
|
and indirection operators.
|
||||||
|
|
||||||
|
Compliant example::
|
||||||
|
|
||||||
|
int *x;
|
||||||
|
int y = y + *x;
|
||||||
|
int a = b->member;
|
||||||
|
|
||||||
|
.. rst-class:: non-compliant-code
|
||||||
|
|
||||||
|
Non-compliant example::
|
||||||
|
|
||||||
|
int * x;
|
||||||
|
int y = y + * x;
|
||||||
|
int a = b ->member;
|
||||||
|
|
||||||
|
|
||||||
|
WS-08: A single space shall exist right after semicolons in for-loop headers
|
||||||
|
----------------------------------------------------------------------------
|
||||||
|
|
||||||
|
A single space shall exist right after semicolons that separete the different
|
||||||
|
expressions in for-loop headers.
|
||||||
|
|
||||||
|
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 < 5U;i++) {
|
||||||
|
printf("count: %d \n", i);
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Braces
|
||||||
|
======
|
||||||
|
|
||||||
|
BC-01: Braces after if/switch/for/do/while shall be in the same line
|
||||||
|
--------------------------------------------------------------------
|
||||||
|
|
||||||
|
The statement after if/switch/for/do/while shall always be a compound statement
|
||||||
|
with its opening brace in the same line as the keyword.
|
||||||
|
|
||||||
|
Compliant example::
|
||||||
|
|
||||||
|
uint32_t numerator = 32U;
|
||||||
|
uint32_t denominator = 0U;
|
||||||
|
uint32_t quotient;
|
||||||
|
|
||||||
|
if (denominator != 0U) {
|
||||||
|
quotient = numerator / denominator;
|
||||||
|
}
|
||||||
|
|
||||||
|
.. rst-class:: non-compliant-code
|
||||||
|
|
||||||
|
Non-compliant example::
|
||||||
|
|
||||||
|
uint32_t numerator = 32U;
|
||||||
|
uint32_t denominator = 0U;
|
||||||
|
uint32_t quotient;
|
||||||
|
|
||||||
|
if (denominator != 0U)
|
||||||
|
{
|
||||||
|
quotient = numerator / denominator;
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
BC-02: A function body shall start with a line containing a single opening brace
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
Compliant example::
|
||||||
|
|
||||||
|
uint32_t func_showcase(uint32_t param)
|
||||||
|
{
|
||||||
|
return param;
|
||||||
|
}
|
||||||
|
|
||||||
|
.. rst-class:: non-compliant-code
|
||||||
|
|
||||||
|
Non-compliant example::
|
||||||
|
|
||||||
|
uint32_t func_showcase(uint32_t param) {
|
||||||
|
return param;
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Alignment
|
||||||
|
=========
|
||||||
|
|
||||||
|
AL-01: A 'switch' statement and its subordinate 'case' shall be aligned
|
||||||
|
-----------------------------------------------------------------------
|
||||||
|
|
||||||
|
Compliant example::
|
||||||
|
|
||||||
|
switch(suffix) {
|
||||||
|
case 'u':
|
||||||
|
do_something();
|
||||||
|
break;
|
||||||
|
default:
|
||||||
|
do_something_else();
|
||||||
|
break;
|
||||||
|
}
|
||||||
|
|
||||||
|
.. rst-class:: non-compliant-code
|
||||||
|
|
||||||
|
Non-compliant example::
|
||||||
|
|
||||||
|
switch(suffix) {
|
||||||
|
case 'u':
|
||||||
|
do_something();
|
||||||
|
break;
|
||||||
|
default:
|
||||||
|
do_something_else();
|
||||||
|
break;
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
AL-02: Function parameters shall be aligned
|
||||||
|
-------------------------------------------
|
||||||
|
|
||||||
|
When function call parameters are not in single line, the parameters shall be
|
||||||
|
aligned only with tabs. Mixed-use of spaces and tabs shall not be allowed. The
|
||||||
|
number of tabs could be decided by the developers based on each case and it
|
||||||
|
shall be the same for one case.
|
||||||
|
|
||||||
|
Compliant example::
|
||||||
|
|
||||||
|
uint32_t showcase;
|
||||||
|
|
||||||
|
showcase = func(param_1,
|
||||||
|
param_2,
|
||||||
|
param_3);
|
||||||
|
|
||||||
|
.. rst-class:: non-compliant-code
|
||||||
|
|
||||||
|
Non-compliant example::
|
||||||
|
|
||||||
|
uint32_t showcase;
|
||||||
|
|
||||||
|
showcase = func(param_1,
|
||||||
|
param_2,
|
||||||
|
param_3);
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Comments
|
||||||
|
========
|
||||||
|
|
||||||
|
CM-01: '//' shall not be used for single-line comments
|
||||||
|
-------------------------------------------------------
|
||||||
|
|
||||||
|
'/\* \*/' shall be used to replace '//' for single-line comments.
|
||||||
|
|
||||||
|
Compliant example::
|
||||||
|
|
||||||
|
/* This is a comment */
|
||||||
|
|
||||||
|
.. rst-class:: non-compliant-code
|
||||||
|
|
||||||
|
Non-compliant example::
|
||||||
|
|
||||||
|
// This is a comment
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user