mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-07-05 03:26:29 +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);
|
||||
|
||||
|
||||
ST-14: A space shall exist between the expression and the control keywords
|
||||
==========================================================================
|
||||
|
||||
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
|
||||
ST-14: Infinite loop shall not exist
|
||||
====================================
|
||||
|
||||
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:
|
||||
@ -1456,7 +1391,7 @@ Compliant example::
|
||||
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
|
||||
@ -1478,7 +1413,7 @@ Compliant example::
|
||||
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
|
||||
@ -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
|
||||
@ -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.
|
||||
@ -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::
|
||||
@ -1608,7 +1543,7 @@ Compliant example::
|
||||
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::
|
||||
@ -2787,3 +2722,392 @@ Compliant example::
|
||||
#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