diff options
Diffstat (limited to 'eng/coding-conventions.rst')
| -rw-r--r-- | eng/coding-conventions.rst | 104 |
1 files changed, 60 insertions, 44 deletions
diff --git a/eng/coding-conventions.rst b/eng/coding-conventions.rst index b85d8fc..b56d3c2 100644 --- a/eng/coding-conventions.rst +++ b/eng/coding-conventions.rst @@ -9,26 +9,33 @@ 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 Doxygen according to our :ref:`DoxygenGuidelines`. + +* Use the file templates, see :ref:`FileTemplates`. + * 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. + +* 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 -------- @@ -124,32 +131,6 @@ Language and Compiler * 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. - Readability ------------ @@ -225,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. @@ -238,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. @@ -251,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 -------- |