NOTE: This document is a work-in-progress and might be incomplete.
1. White Space
2.1 No Tabs
2.4 Directories and File Names
2. Layout
2.1 No Tabs
2.4 Directories and File Names
6. Object Oriented Programming in C
Coding style refers to formatting, layout and styling of the source code as well as naming conventions and commenting guidelines. Adopting a documented coding style is the first and perhaps the easiest step towards improving code portability, readability, uniformity and maintainability. All this results in lower cost of software ownership by promoting consistency and avoiding misinterpretations and guessing.
The Quantum Leaps' Embedded C/C++ Coding Style (QL-C/C++:2022) has been designed specifically with safety-related embedded software in mind, where the code needs to undergo certification to a safety standard, such as IEC 61508, IEC 62304, DO-178B/C, etc. Most functional safety standards recommend using safer subsets of the C or C++ programming languages. For example, coding standards MISRA-C:2012 or AUTOSAR-C++14 specify such safer subsets of C90/C99 and C++14, respectively.
This Quantum Leaps' Embedded C/C++ Coding Style (QL-C/C++:2022) is intended to complement the coding standards focused on subsetting the C or C++ programming language. Indeed, both MISRA-C:2012 and AUTOSAR-C++14 explicitly state that stylistic issues and code layout is intentionally left out in those standards. At the same time, they acknowledge and highly recommend that every project adapts a clear styling convention. This Coding Style fills that gap.
NOTE: In order to avoid any confusion, this document is called "Coding Style" as opposed to a "Coding Standard".
Guidelines for Language Sub-setting vs. Guidelines for Layout and Style
In order to reduce duplication, this Coding Style intentionally ommits the guidelines already present in the language-subsetting standards. Even so, there is necessarily some overlap, when the coding standards impose rules that are stylistic in nature. For example, MISRA-C:2012 required Rule 15.6 "The body of an iteration-statement or selection-statement shall be a compound statement" coincides with the stylistic issue of using braces in this Coding Style. But in all such cases, great care has been taken to avoid any conflicts between this Coding Style and MISRA-C or AUTOSAR-C++ Coding Standards.
This Coding Style tries to avoid arbitrary rules and instead supplies a rationale that explains how every proposed guideline helps preventing defects, improves understandability, or avoids confusion. Experience shows that once software developers understand why a given rule is helpful or how it prevents problems, they tend to better remember the rule and actually follow it.
This Coding Style began as an internal document to specify the coding style used in the book "Practical Statecharts in C/C++" [PSiCC] published in June 2002. Later, this style has been modified for the publication of the second edition of the book "Practical UML Statecharts in C/C++, 2nd Edition" [PSiCC2] in October 2008. Later this style has been published as the Quantum Leaps Application Note C/C++ Coding Standard [QL-C/C++:2013], last revised in 2013. This version has been revised for QP/C/C++ 7.0.0 and re-formatted again for publication on GitHub in 2022.
Copyright (c) 2005-2022 Quantum Leaps (www.state-machine.com).
This "Quantum Leaps Embedded C/C++ Coding Style (QL-C/C++:2022)" is licensed under the terms of the GNU Free Documentation License, Version 1.3 or any later version (SPDX-License-Identifier: GFDL-1.3-or-later) published by the Free Software Foundation. A copy of the license is available in the file LICENSE.txt including in this Git repository.
The Quantum Leaps' Embedded C/C++ Coding Style (QL-C/C++:2022) is published as a set of editable markdown files and example code on GitHub with the explicit intent of being customizable. Customization of the guidelines presented herein may be done simply by forking this Git repository and applying the desired changes. The only conditions that we request are:
- that the original Copyright notice with the link to our website be preserved; and
- that the customized style bears a clear note informing the recipients that it has been modified from the original.
| [C90] | ISO/IEC9899:1990, Programming Languages – C, ISO, 1990. |
| [C99] | ISO/IEC9899:1999, Programming Languages – C, ISO, 1999. |
| [MISRA-C:2012] | MISRA C:2012 Guidelines for the use of the C language in critical systems, MIRA, March 2013. |
| [MISRA-C++:2008] | MISRA C++ Guidelines for the use of the C++ language in critical systems, MIRA, June 2008. |
| [AUTOSAR-C++14] | Guidelines for the use of the C++14 language in critical and safety-related systems, AUTOSAR AP, Release 2017-03. |
| [QL-C/C++:13] | Quantum Leaps, Application Note: C/C++ Coding Standard, 2013, https://www.state-machine.com/doc/AN_QL_Coding_Standard.pdf |
| [BARR-CS:2018] | Michael Barr, Embedded C Coding Standard (BARR-C:2018), 2018, https://barrgroup.com/coding-standard |
| [PSiCC:02] | Miro Samek, Practical Statecharts in C/C++, CMP Books 2002. https://www.state-machine.com/psicc |
| [PSiCC2:08] | Miro Samek, Practical UML Statecharts in C/C++, 2nd Edition, Newnes 2008. https://www.state-machine.com/psicc2 |
| [CODE2:04] | Steve McConnell, Code Complete, 2nd Ed,Microsoft Press 2004. |
| [K&R:88] | Brian Kernighan, Dennis Riche, The C Programming Language, 2nd Ed, Prentice Hall, 1988. |
| [PPP:11] | Bjarne Stroustrup, PPP Style Guide, September 2011, https://www.stroustrup.com/Programming/PPP-style.pdf |
| [FDS:07] | Jack Ganssle, A Firmware Development Standard, Version 1.4, Updated May, 2007 http://www.ganssle.com/fsm.htm |
| [OOP-C:08] | Quantum Leaps, Object-Oriented Programming in C, https://www.state-machine.com/oop |
| [DbC:16] | Quantum Leaps, Key Concept: Design by Contract, https://www.state-machine.com/dbc |