Changeset 75f2463 in rtems-docs


Ignore:
Timestamp:
Dec 9, 2018, 3:50:04 PM (5 months ago)
Author:
Pritish Jain <pritishjain2001@…>
Branches:
master
Children:
a7dc083
Parents:
cc826d7
git-author:
Pritish Jain <pritishjain2001@…> (12/09/18 15:50:04)
git-committer:
Joel Sherrill <joel@…> (12/18/18 00:45:50)
Message:

eng/coding-conventions.rst: Convert TBD to Rest Format (GCI 2018)

File:
1 edited

Legend:

Unmodified
Added
Removed
  • eng/coding-conventions.rst

    rcc826d7 r75f2463  
    44.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project
    55
     6.. COMMENT:TBD  - Convert the following to Rest and insert into this file
     7.. COMMENT:TBD  - https://devel.rtems.org/wiki/Developer/Coding/Conventions
     8
    69Coding Conventions
    710******************
    811
    9 TBD  - Convert the following to Rest and insert into this file
    10 TBD  - https://devel.rtems.org/wiki/Developer/Coding/Conventions
     12The style of RTEMS is generally consistent in the core areas.
     13This page attempts to capture generally accepted practices.
     14When in doubt, consult the code around you or look in cpukit/rtems.
     15See the sister page `Doxygen Recommendations <https://devel.rtems.org/wiki/Developer/Coding/Doxygen>`_.
     16for examples that illustrate style rules and Doxygen usage.
     17
     18Source Documentation
     19--------------------
     20
     21* Use Doxygen according to our `Doxygen Recommendations <https://devel.rtems.org/wiki/Developer/Coding/Doxygen>`_..
     22* Start each file with a brief description followed by a license.
     23  See `Boilerplate File Header <https://devel.rtems.org/wiki/Developer/Coding/Boilerplate_File_Header>`_..
     24* Use /* */ comments.
     25* Use comments wisely within function bodies, to explain
     26  or draw attention without being verbose.
     27* Use English prose and strive for good grammar,
     28  spelling, and punctuation.
     29* Use TODO: with a comment to indicate code that needs improvement.
     30  Make it clear what there is to do.
     31* Use XXX or FIXME to indicate an error/bug/broken code.
     32
     33Licenses
     34--------
     35
     36* The RTEMS `License <https://devel.rtems.org/wiki/TBR/Website/License>`_. is the typical
     37  and preferred license.
     38  * 2- and 3-clause BSD, MIT, and other OSI-approved non-copyleft licenses
     39    that permit statically linking with the code of different licenses
     40    are acceptable.
     41  * GPL licensed code is NOT acceptable, neither is LGPL.
     42    See `this blog post explanation <http://gedare-csphd.blogspot.com/2013/05/software-licenses-with-rtems.html>`_.
     43    for more information.
     44  * Advertising obligations are NOT acceptable, but restrictions are permissible.
     45
     46Language and Compiler
     47---------------------
     48
     49* Use C99.
     50* Treat warnings as errors: eliminate them.
     51* Favor C, but when assembly language is required use inline
     52  assembly if possible.
     53* Do not use compiler extensions.
     54* Use the RTEMS_macros defined in score/basedefs.h for abstracting
     55  compiler-specific features.
     56* Use NULL for the null pointer, and prefer to use explicit
     57  checks against NULL, e.g.,
     58
     59  .. code-block:: c
     60
     61      if ( ptr != NULL )
     62  instead of
     63
     64  .. code-block:: c
     65
     66      if ( !ptr )
     67* Use explicit checks for bits in variables.
     68   * Example 1: Use
     69      .. code-block:: c
     70
     71           if ( XBITS == (var & XBITS) )
     72     to check for a set of defined bits.
     73   * Example 2: Use
     74      .. code-block:: c
     75
     76          if ( (var & X_FLAGS) != 0) )
     77     instead of
     78      .. code-block:: c
     79
     80          if ( !!(var & X_FLAGS) )
     81     to check for at least 1 defined bit in a set.
     82* Use '(void) unused;' to mark unused parameters and set-but-unused
     83  variables immediately after being set.
     84* Do not put function prototypes in C source files, any global functions
     85  should have a prototype in a header file and any private function
     86  should be declared static.
     87* Declare global variables in exactly one header file.
     88  Define global variables in at most one source file.
     89  Include the header file declaring the global variable as
     90  the first include file if possible to make sure that the
     91  compiler checks the declaration and definition and that
     92  the header file is self-contained.
     93* Do not cast arguments to any printf() or printk() variant.
     94  Use <inttypes.h> PRI constants for the types supported there.
     95  Use <rtems/inttypes.h> for the other POSIX and RTEMS types that
     96  have PRI constants defined there. This increases the portability
     97  of the printf() format.
     98* Do not use the register keyword. It is deprecated since C++14.
     99
     100Formatting
     101-----------
     102
     103* Use spaces instead of tabs.
     104* Use two spaces for indentation, four spaces for
     105  hanging indentation.
     106* Adhere to a limit of `80 characters per line <https://devel.rtems.org/wiki/Developer/Coding/80_characters_per_line>`_..
     107* Put function return types and names on one line if they fit.
     108* Put function calls on one line if they fit.
     109* No space between a function name or function-like macro and
     110  the opening parens.
     111* Put braces on the same line as and one space after the
     112  conditional expression ends.
     113* Put the opening brace of a function definition one line after
     114  the closing parenthesis of its prototype.
     115* Put a single space inside and outside of each parenthesis
     116  of a conditional expression.
     117  * Exception: never put a space before a closing semi-colon.
     118* Put a single space before and after ternary operators.
     119* Put a single space before and after binary operators.
     120* Put no space between unary operators (e.g. *, &, !, ~, ++, --)
     121  and their operands.
     122* No spaces around dereferencing operators (-> and .).
     123* Do not use more than one blank line in a row.
     124* Do not use trailing whitespace at the end of a line.
     125
     126Readability
     127------------
     128
     129* Understand and follow the `naming rules <https://devel.rtems.org/wiki/Developer/Coding/NamingRules>`_..
     130* Use typedef to remove 'struct', but do not use typedef
     131  to hide pointers or arrays.
     132  * Exception: typedef can be used to simplify function pointer types.
     133
     134* Do not mix variable declarations and code.
     135* Declare variables at the start of a block.
     136* Only use primitive initialization of variables at their declarations.
     137  Avoid complex initializations or function calls in variable declarations.
     138* Do not put unrelated functions or data in a single file.
     139* Do not declare functions inside functions.
     140* Avoid deep nesting by using early exits e.g. return, break, continue.
     141  * Parameter checking should be done first with early error returns.
     142  * Avoid allocation and critical sections until error checking is done.
     143  * For error checks that require locking, do the checks early after acquiring locks.
     144  * Use of 'goto' requires good reason and justification.
     145
     146* Test and action should stay close together.
     147* Avoid complex logic in conditional and loop statements.
     148* Put conditional and loop statements on the line after the expression.
     149* Favor inline functions to hide
     150  `compile-time feature-conditioned compilation <https://devel.rtems.org/wiki/Developer/Coding/Compile-time_feature-conditioned_compilation>`_..
     151* Define non-inline functions in a .c source file.
     152* Declare all global (non-static) functions in a .h header file.
     153* Declare and define inline functions in one place. Usually, this
     154  is a *impl.h header file.
     155* Declare and define static functions in one place. Usually, this is
     156  toward the start of a .c file. Minimize forward declarations of
     157  static functions.
     158* Function declarations should include variable names.
     159* Avoid excess parentheses. Learn the
     160  `operator precedence <https://en.wikipedia.org/wiki/Operators_in_C_and_C%2B%2B#Operator_precedence>`_. rules.
     161* Always use parentheses with sizeof. This is an exception to the rule
     162  about excess parentheses.
     163
     164Robustness
     165-----------
     166
     167* Check all return statuses.
     168* Validate input parameters.
     169* Use debug assertions (assert).
     170* Use const when appropriate for read-only function parameters
     171  and compile-time constant values.
     172* Do not hard code limits such as maximum instances into your code.
     173* Prefer to use sizeof(variable) instead of sizeof(type).
     174* Favor C automatic variables over global or static variables.
     175* Use global variables only when necessary and ensure
     176  atomicity of operations.
     177* Do not shadow variables.
     178* Avoid declaring large buffers or structures on the stack.
     179* Avoid using zero (0) as a valid value. Memory often
     180  defaults to being zero.
     181* Favor mutual exclusion primitives over disabling preemption.
     182* Avoid unnecessary dependencies, such as by not calling
     183  ''printf()'' on error paths.
     184* Avoid inline functions and macros with complicated logic
     185  and decision points.
     186* Prefer inline functions, enum, and const variables instead of CPP macros.
     187* CPP macros should use a leading underscore for parameter
     188  names and `avoid macro pitfalls <https://gcc.gnu.org/onlinedocs/cpp/Macro-Pitfalls.html#Macro-Pitfalls>`_..
     189
     190Portability
     191-----------
     192
     193* Think portable! RTEMS supports a lot of target hardware.
     194* For integer primitives, prefer to use precise-width integer
     195  types from C99 stdint.h.
     196* Write code that is 16-bit, 32-bit, and 64-bit friendly.
     197
     198Maintainability
     199---------------
     200
     201* Minimize modifications to `third-party code <https://devel.rtems.org/wiki/Developer/Coding/ThirdPartyCode>`_..
     202* Keep it simple! Simple code is easier to debug and easier to read than clever code.
     203* Share code with other architectures, CPUs, and BSPs where possible.
     204* Do not duplicate standard OS or C Library routines.
     205
     206Performance
     207-----------
     208
     209* Prefer algorithms with the `lowest order of time and space <https://devel.rtems.org/wiki/FAQ/AlgorithmicComplexity>`_.
     210  for fast, deterministic execution times with small memory footprints.
     211* Understand the constraints of `real-time programming <https://devel.rtems.org/wiki/TBR/Review/Real-Time_Resources>`_..
     212  Limit execution times in interrupt contexts and critical sections,
     213  such as Interrupt and Timer Service Routines (TSRs).
     214* Functions used only through function pointers should be declared
     215  'static inline' (RTEMS_INLINE_ROUTINE)
     216* Prefer to ++preincrement instead of postincrement++.
     217* Avoid using floating point except where absolutely necessary.
     218
     219Miscellaneous
     220-------------
     221
     222* If you need to temporarily change the execution mode of a
     223  task/thread, restore it.
     224* If adding code to ''cpukit'' be sure the filename is unique since
     225  all files under that directory get merged into a single library.
     226
     227Layering
     228--------
     229
     230* TBD: add something about the dependencies and header file layering.
     231* Understand the `RTEMS Software Architecture <https://devel.rtems.org/wiki/TBR/UserManual/RTEMS_Software_Architecture>'_.
     232
     233Exceptions to the Rules
     234-----------------------
     235
     236* Minimize reformatting existing code in RTEMS unless the file undergoes
     237  substantial non-style changes.
     238* `Third-party code <https://devel.rtems.org/wiki/Developer/Coding/ThirdPartyCode>`_.
     239  should not be reformatted to fit RTEMS style.
     240  Exception: unmaintained third-party code adopted and
     241  maintained by RTEMS may be reformatted, subject to the
     242  above rules.
     243
     244Tools
     245-----
     246
     247Some of the above can be assisted by tool support. Feel free to add
     248more tools, configurations, etc here.
     249
     250* `Uncrustify <http://uncrustify.sourceforge.net/>`_.
     251  Configuration for RTEMS:
     252  `rtems.uncrustify <https://devel.rtems.org/attachment/wiki/Developer/Coding/Conventions/rtems.uncrustify>`_.
Note: See TracChangeset for help on using the changeset viewer.