Site Tools


iotivity_c_coding_standards

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
iotivity_c_coding_standards [2015/02/12 09:35]
joncruz [Comments] linked to page for more detail on comments
iotivity_c_coding_standards [2015/03/18 23:12]
ossama [General Standards] Point out intptr_t and uintptr_t in integer/pointer cast discussion.
Line 1: Line 1:
-The following standards define the standard format of C++ code for the IoTivity project and shall be adhered to except where the standard conflicts with existing standards used within a given project. ​ Above all, be consistent in style within the project.+The following standards define the standard format of %%C++%% code for the IoTivity project and shall be adhered to except where the standard conflicts with existing standards used within a given project. ​ Above all, be consistent in style within the project.
  
 ====== Style ====== ====== Style ======
  
-Standards annotated with [C/C++] apply to both C and C++ code.  Standards marked with [C++] apply to C or C++ code that will be compiled with a C compiler. ​ Standards marked with [C] apply to code that will only be compiled with a C compiler.+Standards annotated with [C/C%%++%%] apply to both C and %%C++%% code.  Standards marked with [C%%++%%] apply to C or C%%++%% code that will be compiled with a C compiler. ​ Standards marked with [C] apply to code that will only be compiled with a C compiler.
  
 ===== General Standards ===== ===== General Standards =====
  
-  * All code shall use an indentation width of 4 spaces, and no tabs may be used to indent code. Editors should be [[iotivity_coding_standards|configured]] to provide this standard automatically. When editing code, which does not follow this standard, favor the standard already in use in the existing code, eliminating tabs if possible. ​ [C/C++] +  * All code shall use an indentation width of 4 spaces, and no tabs may be used to indent code. Editors should be [[iotivity_coding_standards|configured]] to provide this standard automatically. When editing code, which does not follow this standard, favor the standard already in use in the existing code, eliminating tabs if possible. ​ [C/C%%++%%
-  * Typically, line length should be limited between 80 and 100 characters, however exceptions are allowed for deeply nested loop and conditional constructs (always look for ways to simplify such constructs first). Wrapped lines should continue the current expression with additional indentation to clarify that the expression has been wrapped. Indent such lines logically (i.e. function parameters and logically grouped expressions should align vertically). ​ [C/C++] +  * Typically, line length should be limited between 80 and 100 characters, however exceptions are allowed for deeply nested loop and conditional constructs (always look for ways to simplify such constructs first). Wrapped lines should continue the current expression with additional indentation to clarify that the expression has been wrapped. Indent such lines logically (i.e. function parameters and logically grouped expressions should align vertically). ​ [C/C%%++%%
-  * Code must compile with no warnings at the standard warning level without flags forcing any warnings off. Exceptions are allowed only for warnings that occur within any external SDKs used or warnings that cannot be eliminated without using pragmatics (e.g. for nested STL templates, certain compilers will warn that names have been truncated). For these cases, ''#​pragma''​ directives may be used to eliminate the warning, but only for the module in which the warning occurs. ​ [C/C++] +  * Code must compile with no warnings at the standard warning level without flags forcing any warnings off. Exceptions are allowed only for warnings that occur within any external SDKs used or warnings that cannot be eliminated without using pragmatics (e.g. for nested STL templates, certain compilers will warn that names have been truncated). For these cases, ''#​pragma''​ directives may be used to eliminate the warning, but only for the module in which the warning occurs. ​ [C/C%%++%%
-  * Structure packing should be left at the compiler default value unless structures are declared for specific calls to external SDKs or used for over-the-air protocols. In such cases the ''#​pragma''​ directives should be localized to the required headers and used in a push/pop context (unless that is unsupported by the compiler). ​ [C/C++] +  * Structure packing should be left at the compiler default value unless structures are declared for specific calls to external SDKs or used for over-the-air protocols. In such cases the ''#​pragma''​ directives should be localized to the required headers and used in a push/pop context (unless that is unsupported by the compiler). ​ [C/C%%+%%+] 
-  * Avoid lengthy functions. Break up functions into smaller functional units where possible unless constructing a deeply nested loop which must run under severe time constraints (e.g. in a 3D rendering or 2D filtering scenario). ​ [C/C++] +  * Avoid lengthy functions. Break up functions into smaller functional units where possible unless constructing a deeply nested loop which must run under severe time constraints (e.g. in a 3D rendering or 2D filtering scenario). ​ [C/C%%++%%
-  * Preprocessor directives should begin on the first column of the line unless they are being explicitly nested. ​ [C/C++] +  * Preprocessor directives should begin on the first column of the line unless they are being explicitly nested. ​ [C/C%%++%%
-  * Pointers must not be cast directly to integers except where forced by an API function. In general an integer the size of a pointer can be made available and may be used when absolutely necessary. ​ If you choose to cast pointers to ''​int''​ and ''​int''​s to pointers provide a comment with the reason. ​ [C/C++]+  * Pointers must not be cast directly to integers except where forced by an API function. In general an integer the size of a pointer ​(e.g. ''​intptr_t''​ or ''​uintptr_t''​) ​can be made available and may be used when absolutely necessary. ​ If you choose to cast pointers to ''​int''​ and ''​int''​s to pointers provide a comment with the reason. ​ [C/C%%++%%]
   * Initialize all variables before they are used. When initializing C-style structures, prefer<​code cpp>   * Initialize all variables before they are used. When initializing C-style structures, prefer<​code cpp>
 Type var = {0}; Type var = {0};
Line 19: Line 19:
 Type var; Type var;
 memset(&​var,​ 0, sizeof(var));​ memset(&​var,​ 0, sizeof(var));​
-</​code>​as the former will complain correctly if the initialization is unsupported due to C++ constructor semantics. ​ For consistency maintain this preference in C code as well as C++.  [C/C++] +</​code>​as the former will complain correctly if the initialization is unsupported due to C%%++%% constructor semantics. ​ For consistency maintain this preference in C code as well as C%%++%%.  [C/C%%++%%
-  * Where functionality is available through multiple external sources, the order of preference is the C/C++ standard libraries, a cross platform external library, or a platform specific library. ​ For example, integer types defined in ''​stdint.h''​ (''​uint8_t'',​ ''​uint16_t'',​ etc.) are preferred over Windows types like ''​BYTE_T''​ or ''​DWORD_T'',​ except where required for platform interface compatibility. ​ Exceptions can be made when not all platforms support the same standard of the C/C++ library. ​ [C/C++]+  * Where functionality is available through multiple external sources, the order of preference is the C/C%%++%% standard libraries, a cross platform external library, or a platform specific library. ​ For example, integer types defined in ''​stdint.h''​ (''​uint8_t'',​ ''​uint16_t'',​ etc.) are preferred over Windows types like ''​BYTE_T''​ or ''​DWORD_T'',​ except where required for platform interface compatibility. ​ Exceptions can be made when not all platforms support the same standard of the C/C%%++%% library. ​ [C/C%%++%%]
  
 ===== Comments ===== ===== Comments =====
  
-  * Comments should be used liberally throughout the code to clarify non-obvious code.  [C/C++] +  * Comments should be used liberally throughout the code to clarify non-obvious code.  [C/C%%++%%
-  * For all external API elements, comments on classes, structures, enumerations,​ member functions and member variable declarations must enumerate all behaviors of the element, including error and exceptional conditions. These comments shall conform to the standards of the current documentation tool, [[http://​www.doxygen.org/​|Doxygen]]. ​ [C/C++] For example:<​code cpp>+  * For all external API elements, comments on classes, structures, enumerations,​ member functions and member variable declarations must enumerate all behaviors of the element, including error and exceptional conditions. These comments shall conform to the standards of the current documentation tool, [[http://​www.doxygen.org/​|Doxygen]]. ​ [C/C%%++%%] For example:<​code cpp>
 /** /**
  * Assignment operator for ByteBuffer.  * Assignment operator for ByteBuffer.
iotivity_c_coding_standards.txt · Last modified: 2015/03/18 23:12 by ossama