wiki:Developer/Coding/Conventions

Version 47 (modified by Gedare, on May 30, 2014 at 5:47:27 PM) (diff)

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 for examples that illustrate style rules and Doxygen usage.

Source Documentation

  • Use Doxygen according to our Doxygen Recommendations.
  • Use /* */ comments.
  • Start each file with a brief description followed by a license. See Boilerplate File Header.
  • Use comments wisely within function bodies, to explain or draw attention without being verbose.
  • Use English 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.

Licenses

  • The RTEMS 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 code of different licenses are acceptable.
    • GPL licensed code is NOT acceptable, neither is LGPL. See this blog post explanation for more information.
    • Advertising obligations are NOT acceptable, but restrictions are permissible.

Language and Compiler

  • Use C99.
  • Favor C, but when assembly language is required use inline assembly if possible.
  • Do not use compiler extensions.
  • Pay attention to warnings. Strive to eliminate them.

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.
  • Put function return types and names on one line if they fit. Put function calls on one line if they fit. If not, put each function argument on its own line with no argument on the first line, and put the closing parenthesis on its own line.
  • Put braces one space after the conditional expression ends.
  • Put a single space inside and outside of each parenthesis of a conditional expression.
  • Put a single space before and no space after unary pointer operators (* and &).
  • No spaces around dereferencing operators (-> and .).
  • Avoid excess parentheses. Learn the operator precedence rules.
  • Do not use more than one blank line in a row.
  • Do not use trailing whitespace at the end of a line.
  • Understand and follow the naming rules.

Readability

  • Do not mix variable declarations and code.
  • Declare variables at the start of a block.
  • Only use primitive initialization of variables at their declarations. Avoid complex initializations or function calls in variable declarations.
  • Do not put unrelated functions or data in a single file.
  • Avoid deep nesting by using early returns
    • Parameter checking should be done first with early error returns.
    • Avoid allocation and critical sections until error checking is done.
    • For error checks that require locking, do the checks early after acquiring locks.
    • Use of 'goto' requires good reason and justification.
  • Test and action should stay close together.
  • Avoid complex logical expressions in ifs, fors, and whiles
  • Favor inline functions to hide compile-time feature-conditioned compilation?.
  • Declare and define inline functions and macros in one place.

Robustness

  • Check all return statuses.
  • Use debug assertions.
  • Do not hard code limits such as maximum instances into your code.
  • Favor C automatic variables over global or static variables.
  • Use global variables only when necessary and ensure atomicity of operations.
  • Do not shadow variables.
  • Avoid declaring large buffers or structures on the stack.
  • Favor mutual exclusion primitives over disabling preemption.
  • Avoid unnecessary dependencies, such as by not calling printf() on error paths.
  • Avoid inline functions and macros with complicated logic and decision points.
  • CPP macros should use a leading underscore for parameter names and avoid macro pitfalls.

Miscellaneous

  • Think portable! RTEMS supports a lot of target hardware.
  • Use algorithms with the lowest order of execution. By favoring O(constant) over O(n) algorithms, RTEMS works hard to ensure deterministic execution times as much as possible.
  • If you need to temporarily change the execution mode of a task/thread, restore it.
  • Minimize modifications to third party code.
  • 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.
  • If adding code to cpukit be sure the filename is unique since all files under that directory get merged into a single library.
  • Limit execution times in Interrupt and Timer Service Routines (TSRs). TSRs scheduled by rtems_timer_fire_XXX run in the context of the clock tick ISR while TSRs scheduled by rtems_timer_server_fire_XXX run in the context of a dedicated Timer Server task. Either way, excessive execution times could have a negative impact on the system performance.

Layering

TBD: add something about the dependencies and header file layering.

=Exceptions to the Rules=

TBD

Attachments (1)

Download all attachments as: .zip