diff --git a/doc/developer-guides/coding_guidelines.rst b/doc/developer-guides/coding_guidelines.rst new file mode 100644 index 000000000..2c928f96a --- /dev/null +++ b/doc/developer-guides/coding_guidelines.rst @@ -0,0 +1,477 @@ +.. _coding_guidelines: + +Coding Guidelines +################# + +.. contents:: + :local: + + +Compilation Units +***************** + +CU-01: Only one assignment shall be on a single line +==================================================== + +Multiple assignments on a single line are not allowed. + +Compliant example:: + + a = d; + b = d; + c = d; + +.. rst-class:: non-compliant-code + + Non-compliant example:: + + int a = b = c = d; + + +CU-02: Only one return statement shall be in a function +======================================================= + +Multiple return statements in a function are not allowed. + +Compliant example:: + + int32_t foo(char *ptr) { + int32_t ret; + if (ptr == NULL) { + ret = -1; + } else { + ... + ret = 0; + } + return ret; + } + +.. rst-class:: non-compliant-code + + Non-compliant example:: + + int32_t foo(char *ptr) { + if (ptr == NULL) { + return -1; + } + ... + return 0; + } + + + +Declarations and Initialization +******************************* + +DI-01: Variable shall be used after its initialization +====================================================== + +Compliant example:: + + uint32_t a, b; + + a = 0U; + b = a; + +.. rst-class:: non-compliant-code + + Non-compliant example:: + + uint32_t a, b; + + b = a; + + +DI-02: Function shall be called after its declaration +===================================================== + +Compliant example:: + + static void showcase_2(void) + { + /* main body */ + } + + static void showcase_1(void) + { + showcase_2(void); + } + +.. rst-class:: non-compliant-code + + Non-compliant example:: + + static void showcase_1(void) + { + showcase_2(void); + } + + static void showcase_2(void) + { + /* main body */ + } + + +DI-03: The initialization statement shall not be skipped +======================================================== + +Compliant example:: + + uint32_t showcase; + + showcase = 0U; + goto increment_ten; + showcase += 20U; + + increment_ten: + showcase += 10U; + +.. rst-class:: non-compliant-code + + Non-compliant example:: + + uint32_t showcase; + + goto increment_ten; + showcase = 0U; + showcase += 20U; + + increment_ten: + showcase += 10U; + + + +Functions +********* + +FN-01: A non-void function shall have return statement +====================================================== + +Compliant example:: + + uint32_t showcase(uint32_t param) + { + printf("param: %d\n", param); + return param; + } + +.. rst-class:: non-compliant-code + + Non-compliant example:: + + uint32_t showcase(uint32_t param) + { + printf("param: %d\n", param); + } + + +FN-02: A non-void function shall have return value rather than empty return +=========================================================================== + +Compliant example:: + + uint32_t showcase(uint32_t param) + { + printf("param: %d\n", param); + return param; + } + +.. rst-class:: non-compliant-code + + Non-compliant example:: + + uint32_t showcase(uint32_t param) + { + printf("param: %d\n", param); + return; + } + + +FN-03: A non-void function shall return value on all paths +========================================================== + +Compliant example:: + + uint32_t showcase(uint32_t param) + { + if (param < 10U) { + return 10U; + } else { + return param; + } + } + +.. rst-class:: non-compliant-code + + Non-compliant example:: + + uint32_t showcase(uint32_t param) + { + if (param < 10U) { + return 10U; + } else { + return; + } + } + + +FN-04: The return value of a void-returning function shall not be used +====================================================================== + +Compliant example:: + + void showcase_1(uint32_t param) + { + printf("param: %d\n", param); + } + + void showcase_2(void) + { + uint32_t a; + + showcase_1(0U); + a = 0U; + } + +.. rst-class:: non-compliant-code + + Non-compliant example:: + + void showcase_1(uint32_t param) + { + printf("param: %d\n", param); + } + + void showcase_2(void) + { + uint32_t a; + + a = showcase_1(0U); + } + + + +Statements +********** + +ST-01: sizeof operator shall not be performed on an array function parameter +============================================================================ + +When an array is used as the function parameter, the array address is passed. +Thus, the return value of the sizeof operation is the pointer size rather than +the array size. + +Compliant example:: + + #define SHOWCASE_SIZE 32U + + void showcase(uint32_t array_source[SHOWCASE_SIZE]) { + uint32_t num_bytes = SHOWCASE_SIZE * sizeof(uint32_t); + + printf("num_bytes %d \n", num_bytes); + } + +.. rst-class:: non-compliant-code + + Non-compliant example:: + + #define SHOWCASE_SIZE 32U + + void showcase(uint32_t array_source[SHOWCASE_SIZE]) { + uint32_t num_bytes = sizeof(array_source); + + printf("num_bytes %d \n", num_bytes); + } + + +ST-02: Argument of strlen shall end with a null character +========================================================= + +Compliant example:: + + uint32_t size; + char showcase[3] = {'0', '1', '\0'}; + + size = strlen(showcase); + +.. rst-class:: non-compliant-code + + Non-compliant example:: + + uint32_t size; + char showcase[2] = {'0', '1'}; + + size = strlen(showcase); + + +ST-03: Two strings shall not be copied to each other if they have memory overlap +================================================================================ + +Compliant example:: + + char *str_source = "showcase"; + char str_destination[32]; + + (void)strncpy(str_destination, str_source, 8U); + +.. rst-class:: non-compliant-code + + Non-compliant example:: + + char *str_source = "showcase"; + char *str_destination = &str_source[1]; + + (void)strncpy(str_destination, str_source, 8U); + + +ST-04: memcpy shall not be performed on objects with overlapping memory +======================================================================= + +Compliant example:: + + char *str_source = "showcase"; + char str_destination[32]; + + (void)memcpy(str_destination, str_source, 8U); + +.. rst-class:: non-compliant-code + + Non-compliant example:: + + char str_source[32]; + char *str_destination = &str_source[1]; + + (void)memcpy(str_destination, str_source, 8U); + + +ST-05: Assignment shall not be performed between variables with overlapping storage +=================================================================================== + +Compliant example:: + + union union_showcase + { + uint8_t data_8[4]; + uint16_t data_16[2]; + }; + + union union_showcase showcase; + + showcase.data_16[0] = 0U; + showcase.data_8[3] = (uint8_t)showcase.data_16[0]; + +.. rst-class:: non-compliant-code + + Non-compliant example:: + + union union_showcase + { + uint8_t data_8[4]; + uint16_t data_16[2]; + }; + + union union_showcase showcase; + + showcase.data_16[0] = 0U; + showcase.data_8[0] = (uint8_t)showcase.data_16[0]; + + +ST-06: The array size shall be valid if the array is function input parameter +============================================================================= + +This is to guarantee that the destination array has sufficient space for the +operation, such as copy, move, compare and concatenate. + +Compliant example:: + + void showcase(uint32_t array_source[16]) + { + uint32_t array_destination[16]; + + (void)memcpy(array_destination, array_source, 16U); + } + +.. rst-class:: non-compliant-code + + Non-compliant example:: + + void showcase(uint32_t array_source[32]) + { + uint32_t array_destination[16]; + + (void)memcpy(array_destination, array_source, 32U); + } + + +ST-07: The destination object shall have sufficient space for operation +======================================================================= + +The destination object shall have sufficient space for operation, such as copy, +move, compare and concatenate. Otherwise, data corruption may occur. + +Compliant example:: + + uint32_t array_source[32]; + uint32_t array_destination[32]; + + (void)memcpy(array_destination, array_source, 32U); + +.. rst-class:: non-compliant-code + + Non-compliant example:: + + uint32_t array_source[32]; + uint32_t array_destination[16]; + + (void)memcpy(array_destination, array_source, 32U); + + +ST-08: The size param to memcpy/memset shall be valid +===================================================== + +The size param shall not be larger than either the source size or destination +size. Otherwise, data corruption may occur. + +Compliant example:: + + #define SHOWCASE_BYTES (32U * sizeof(uint32_t)) + + uint32_t array_source[32]; + + (void)memset(array_source, 0U, SHOWCASE_BYTES); + +.. rst-class:: non-compliant-code + + Non-compliant example:: + + #define SHOWCASE_BYTES (32U * sizeof(uint32_t)) + + uint32_t array_source[32]; + + (void)memset(array_source, 0U, 2U * SHOWCASE_BYTES); + + + +Identifiers +*********** + +ID-01: static keyword shall not be used in an array index declaration +===================================================================== + +Compliant example:: + + char showcase[2] = {'0', '1'}; + char chr; + + chr = showcase[1]; + +.. rst-class:: non-compliant-code + + Non-compliant example:: + + char showcase[2] = {'0', '1'}; + char chr; + + chr = showcase[static 1]; + + diff --git a/doc/developer-guides/index.rst b/doc/developer-guides/index.rst index 20394319d..42497bf4c 100644 --- a/doc/developer-guides/index.rst +++ b/doc/developer-guides/index.rst @@ -27,5 +27,6 @@ project. :maxdepth: 1 contribute_guidelines + coding_guidelines doc_guidelines graphviz