diff options
Diffstat (limited to 'eng/coding-conventions.rst')
| -rw-r--r-- | eng/coding-conventions.rst | 157 |
1 files changed, 100 insertions, 57 deletions
diff --git a/eng/coding-conventions.rst b/eng/coding-conventions.rst index 488ee26..b56d3c2 100644 --- a/eng/coding-conventions.rst +++ b/eng/coding-conventions.rst @@ -9,119 +9,127 @@ Coding Conventions ****************** -The style of RTEMS is generally consistent in the core areas. -This page attempts to capture generally accepted practices. -When in doubt, consult the code around you or look in cpukit/rtems. -See the sister page `Doxygen Recommendations <https://devel.rtems.org/wiki/Developer/Coding/Doxygen>`_. -for examples that illustrate style rules and Doxygen usage. +The style of RTEMS is generally consistent in the core areas. This section +attempts to capture generally accepted practices. When in doubt, consult the +code around you, look in the RTEMS sources in the directories +:file:`cpukit/include/rtems/score` and :file:`cpukit/score`, or ask on the +:r:list:`devel`. Source Documentation -------------------- -* Use Doxygen according to our `Doxygen Recommendations <https://devel.rtems.org/wiki/Developer/Coding/Doxygen>`_.. -* Start each file with a brief description followed by a license. - See `Boilerplate File Header <https://devel.rtems.org/wiki/Developer/Coding/Boilerplate_File_Header>`_.. -* Use /* */ comments. -* Use comments wisely within function bodies, to explain - or draw attention without being verbose. -* Use English prose and strive for good grammar, - spelling, and punctuation. -* Use TODO: with a comment to indicate code that needs improvement. - Make it clear what there is to do. -* Use XXX or FIXME to indicate an error/bug/broken code. +* Use Doxygen according to our :ref:`DoxygenGuidelines`. + +* Use the file templates, see :ref:`FileTemplates`. + +* Use ``/* */`` comments. + +* Do not use ``//`` comments. + +* Use comments wisely within function bodies, to explain or draw attention + without being verbose. + +* Use English prose and strive for good grammar, spelling, and punctuation. + +* Use ``TODO`` with a comment to indicate code that needs improvement. Make + it clear what there is to do. Add a ticket and add a link to it. + +* Use ``XXX`` or ``FIXME`` to indicate an error/bug/broken code. Add a ticket + and add a link to it. Licenses -------- -* The RTEMS `License <https://devel.rtems.org/wiki/TBR/Website/License>`_. is the typical - and preferred license. - * 2- and 3-clause BSD, MIT, and other OSI-approved non-copyleft licenses - that permit statically linking with the code of different licenses - are acceptable. - * GPL licensed code is NOT acceptable, neither is LGPL. - See `this blog post explanation <http://gedare-csphd.blogspot.com/2013/05/software-licenses-with-rtems.html>`_. - for more information. - * Advertising obligations are NOT acceptable, but restrictions are permissible. +The RTEMS Project has strict requirements on the types of software licenses +that apply to software it includes and distributes. Submissions will be +summarily rejected that do not follow the correct license or file header +requirements. + +* Refer to :ref:`LicensingRequirements` for a discussion of the acceptable + licenses and the rationale. + +* Refer to :ref:`FileHeaderCopyright` for example copyright/license comment + blocks for various languages. Language and Compiler --------------------- * Use C99. + * Treat warnings as errors: eliminate them. + * Favor C, but when assembly language is required use inline assembly if possible. + * Do not use compiler extensions. -* Use the RTEMS_macros defined in score/basedefs.h for abstracting - compiler-specific features. + +* Use the RTEMS macros defined in <rtems/score/basedefs.h> for abstracting + compiler-specific features. For using attributes see the + `GCC attribute syntax <https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html#Attribute-Syntax>`_. + Prefer to place attributes in front of the declarator. Try to be in line + with + `C++11 attributes <https://en.cppreference.com/w/cpp/language/attributes>`_ + and C11 keywords such as + `_Noreturn <https://en.cppreference.com/w/c/language/_Noreturn>`_. + * Use NULL for the null pointer, and prefer to use explicit checks against NULL, e.g., .. code-block:: c if ( ptr != NULL ) + instead of .. code-block:: c if ( !ptr ) + * Use explicit checks for bits in variables. + * Example 1: Use + .. code-block:: c if ( XBITS == (var & XBITS) ) + to check for a set of defined bits. + * Example 2: Use + .. code-block:: c if ( (var & X_FLAGS) != 0) ) + instead of + .. code-block:: c if ( !!(var & X_FLAGS) ) + to check for at least 1 defined bit in a set. -* Use '(void) unused;' to mark unused parameters and set-but-unused + +* Use ``(void) unused;`` to mark unused parameters and set-but-unused variables immediately after being set. + * Do not put function prototypes in C source files, any global functions should have a prototype in a header file and any private function should be declared static. + * Declare global variables in exactly one header file. Define global variables in at most one source file. Include the header file declaring the global variable as the first include file if possible to make sure that the compiler checks the declaration and definition and that the header file is self-contained. + * Do not cast arguments to any printf() or printk() variant. Use <inttypes.h> PRI constants for the types supported there. Use <rtems/inttypes.h> for the other POSIX and RTEMS types that have PRI constants defined there. This increases the portability of the printf() format. -* Do not use the register keyword. It is deprecated since C++14. -Formatting ------------ - -* Use spaces instead of tabs. -* Use two spaces for indentation, four spaces for - hanging indentation. -* Adhere to a limit of `80 characters per line <https://devel.rtems.org/wiki/Developer/Coding/80_characters_per_line>`_.. -* Put function return types and names on one line if they fit. -* Put function calls on one line if they fit. -* No space between a function name or function-like macro and - the opening parens. -* Put braces on the same line as and one space after the - conditional expression ends. -* Put the opening brace of a function definition one line after - the closing parenthesis of its prototype. -* Put a single space inside and outside of each parenthesis - of a conditional expression. - * Exception: never put a space before a closing semi-colon. -* Put a single space before and after ternary operators. -* Put a single space before and after binary operators. -* Put no space between unary operators (e.g. *, &, !, ~, ++, --) - and their operands. -* No spaces around dereferencing operators (-> and .). -* Do not use more than one blank line in a row. -* Do not use trailing whitespace at the end of a line. +* Do not use the register keyword. It is deprecated since C++14. Readability ------------ @@ -198,7 +206,7 @@ Portability Maintainability --------------- -* Minimize modifications to `third-party code <https://devel.rtems.org/wiki/Developer/Coding/ThirdPartyCode>`_.. +* Minimize modifications to `third-party code <https://devel.rtems.org/wiki/Developer/Coding/ThirdPartyCode>`_. * Keep it simple! Simple code is easier to debug and easier to read than clever code. * Share code with other architectures, CPUs, and BSPs where possible. * Do not duplicate standard OS or C Library routines. @@ -211,8 +219,6 @@ Performance * Understand the constraints of `real-time programming <https://devel.rtems.org/wiki/TBR/Review/Real-Time_Resources>`_.. Limit execution times in interrupt contexts and critical sections, such as Interrupt and Timer Service Routines (TSRs). -* Functions used only through function pointers should be declared - 'static inline' (RTEMS_INLINE_ROUTINE) * Prefer to ++preincrement instead of postincrement++. * Avoid using floating point except where absolutely necessary. @@ -224,6 +230,43 @@ Miscellaneous * If adding code to ''cpukit'' be sure the filename is unique since all files under that directory get merged into a single library. +Header Files +------------ + +* Do not add top-level header files. Place the header files in a directory, + for example ``#include <rtems/*>``, ``#include <bsp/*>``, + ``#include <dev/*>``, etc. + +* Use the extension :file:`.h` for C header files. + +* Use the extension :file:`.hpp` for C++ header files. + +* Use the file template for header files, see :ref:`CCXXHeaderFileTemplate`. + +* Use separate header files for the API and the implementation. + +* Use :file:`foobar.h` for the header file of the ``foobar`` module which + defines API components. + +* Use :file:`foobardata.h` for the header file of the ``foobar`` module which + defines interfaces used by the application configuration. + +* Use :file:`foobarimpl.h` for the header file of the ``foobar`` module which + defines interfaces, macros, and inline functions used by the implementation. + +* Do not place inline functions which are only used in one implementation + source file into the implementation header file. Add these inline functions + directly to the corresponding source file. + +* Document all elements in header files with comments in Doxygen markup, see + :ref:`DoxygenGuidelines`. + +* Only place header files which should be directly included by the user with an + ``@file`` Doxygen directive into the API documentation group. Place internal + API header files with an ``@file`` Doxygen command into the implementation + documentation group even if they define API elements. The API documentation + group should only list public header files and no internal header files. + Layering -------- |