rockghotreamenla.gqedded C Coding Standard Table of Contents Introduction. A C coding standard is a set of rules for source code that is adopted by a team of programmers working together on a project, such as the design of an. Barr Group's Embedded C Coding Standard focuses on practical Alternatively, you can download a free PDF copy through our online store.
|Language:||English, Spanish, Japanese|
|Distribution:||Free* [*Register to download]|
Barr Group - Embedded C Coding rockghotreamenla.gq - Download as PDF File .pdf), Text File .txt) or Mike Ficco, JR Simma, Dan Smith, Robert Van Rooyen, and. In this book, Michael Barr and Anthony Massa show how the software and including the GNU compiler suite, which is a standard tool widely used in this industry. This is a book about programming embedded systems in C. As such, . Seasoned programmer Michael Barr releases C guidelines containing rules. The free PDF book has a sum of listed rules from his decades of.
Of course, a coding standard cannot by itself eliminate all of the bugs from a complex embedded system. Thus this coding standard should be applied as part of a broader embedded software development and quality assurance process. An appropriate process may be lightweight but must emphasize the importance of software and system architecture as well as programmer skills training and 5 should include at least the use of design reviews, code reviews, and version control.
Other important reasons for adopting this coding standard include increasing the readability and portability of source code, so that firmware may be maintained and reused at lower cost.
A coding standard benefits a team of developers and the larger organization by reducing the time required by individuals to understand or review the work of peers. This coding standard was developed in accordance with the following guiding principles, which served to focus the authors attention and eliminate conflict over items that are sometimes viewed by programmers as personal stylistic preferences: 1.
Individual programmers do not own the software they write. All software development is work for hire for an employer or a client and, thus, the end product should be constructed in a workmanlike manner. It is cheaper and easier to prevent a bug from creeping into code than it is to find and kill it after it has entered. A key strategy in this fight is to write code in which the compiler, linker, or a static 6 analysis tool can detect bugs automaticallyi. Keywords goto, continue, and break often lead to spaghetti code.
Enforcement: The presence of these keywords in new or modified source code shall be detected and reported via an automated tool at each build. The static keyword shall be used to declare all functions and variables that do not need to be visible outside of the module in which they are declared. The const keyword shall be used whenever appropriate. Examples include: i. To declare variables that should not be changed after initialization, ii. To define call-by-reference function parameters that should not be modified e.
To define fields in structs and unions that should not be modified e. As a strongly typed alternative to define for numerical constants. The volatile keyword shall be used whenever appropriate. To declare a global variable accessible by current use or scope by any interrupt service routine, 27 Embedded C Coding Standard ii.
To declare a global variable accessible by current use or scope by two or more tasks, iii. To declare a delay loop counter. At the module-level, global variables and functions declared static are protected from external use. Heavy-handed use of static in this way thus decreases coupling between modules. The const and volatile keywords are even more important.
The upside of using const as much as possible is compiler-enforced protection from unintended writes to data that should be read-only. Proper use of volatile eliminates a whole class of difficult-to-detect bugs by preventing compiler optimizations that would eliminate requested reads or writes to variables or registers. We believe that the vast majority of embedded systems contain bugs waiting to happen due to missing volatile keywords.
Comments shall never be nested. Comments shall never be used to disable a block of code, even temporarily. No block of temporarily disabled code shall remain in the source code of a release candidate. In addition this deviation is consistent with our choice of the [C99] language, which officially added single-line comments to the C language. Any line or block of code that exists specifically to increase the level of debugging output information shall be surrounded by ifndef NDEBUG … endif.
Reasoning: Nested comments and commented-out code both run the risk of allowing unexpected snippets of code to be compiled into the final executable. Enforcement: The use of only acceptable comment formats can be only partially enforced by the compiler or static analysis. The avoidance of commented-out code, for example, must be enforced during code reviews.
In both cases, the programmer acts to disable the verbose code. All comments shall be written in clear and complete sentences, with proper spelling and grammar and appropriate punctuation.
The most useful comments generally precede a block of code that performs one step of a larger algorithm. The comments in front of the block should be at the same indentation level. Avoid explaining the obvious. Assume the reader knows the C programming language. For example, end-of-line comments should only be used in exceptional circumstances, where the meaning of that one line of code may be unclear from the variable and function names and operations alone but where a short comment makes it clear.
The number and length of individual comment blocks shall be proportional to the complexity of the code they describe.
Whenever an algorithm or technical detail has come from a published source, the comment shall include a sufficient reference to the original source via book title, website URL, or other details to allow a reader of the code to find the cited reference material.
Whenever a flow-chart or other diagram is needed to sufficiently document the code, the drawing shall be maintained with the source code under version control and the comments should reference the diagram by file name or title. All assumptions shall be spelled out in comments. Each module and function shall be commented in a manner suitable for automatic documentation generation via Doxygen www. Use the following capitalized comment markers to highlight important issues: i.
For example, that a chunk of driver code deviates from the datasheet because there was an errata in the chip.
Or that an assumption is being made by the original programmer. When appropriate, an all-caps programmer name or set of initials may be included before the word TODO e.
Reasoning: Following these rules results in good comments. And good comments result in good code. Unfortunately, it is easy for source code and documentation to drift over time. The best way to prevent this is to keep the documentation as close to the code as possible.
Doxygen is a useful tool to regenerate documentation describing the modules, functions, and parameters of a project as that code is changed. Exceptions: Individual projects may standardize the use of Doxygen features of beyond those in the template files.
Code reviewers should be on the lookout both that the comments accurately describe the code and that they are clear, concise, and valuable. The left and right brackets of the array subscript operator [ and ] shall always be without surrounding spaces. Expressions within parentheses shall always have no spaces adjacent to the left and right parenthesis characters.
The left and right parentheses of the function call operator shall always be without surrounding spaces, except that the function declaration shall feature one space between the function name and the left parenthesis to allow that one particular mention of the function name to be easily located. Each comma separating function parameters shall always be followed by one space.
Each semicolon separating the elements of a for statement shall always be followed by one space. Each semicolon shall follow the statement it terminates without a preceding space. Reasoning: The placement of white space is as important as the placement of the text of a program. Good use of white space reduces eyestrain and increases the ability of the author and reviewers of the code to spot potential bugs. Enforcement: These rules shall be enforced by an automated tool such as a code beautifier.
The names of variables within a series of declarations shall have their first characters aligned. The names of struct and union members shall have their first characters aligned.
The assignment operators within a block of adjacent assignment statements shall be aligned. The in a preprocessor directive shall always be located in column 1, except when indenting within a if or ifdef sequence. Reasoning: Visual alignment emphasizes similarity. A series of consecutive lines containing variable declarations is easily spotted and understood as a block.
Blank lines and unrelated alignments should be used to visually distinguish unrelated blocks of code appearing nearby.
No line of code shall contain more than one statement. There shall be a blank line before and after each natural block of code. Examples of natural blocks of code are loops, if-else and switch statements, and consecutive declarations.
Each source file shall have a blank line at the end. Exceptions: None Enforcement: These rules shall be enforced during code reviews.
Each indentation level within a module should consist of 4 spaces. Within a switch statement, each case statement should be indented; the contents of the case block should be indented once more. Whenever a line of code is too long to fit within the maximum line width, indent the second and any subsequent lines in the most readable manner possible. Exceptions: The indentation in legacy code modules that are indented differently shall not be changed unless it is anticipated that a significant amount of the code will be modified.
In that case, the indentation across the entire module shall be changed in a distinct version control step. This is because a side effect of changing indentation is the loss of difference tracking capability in the version control system. It is thus valuable to separate the code changes from the indent changes.
Enforcement: An automated tool shall be provided to programmers to convert indentations of other sizes automatically. This tool shall modify all new or changed code prior to each build.
The tab character shall never appear within any module. Reasoning: The width of the tab character varies by editor and programmer preference, making consistent visual layout a continual source of headaches during code reviews and maintenance. Exceptions: Existing tabs in legacy code modules shall not be eliminated unless it is anticipated that a significant amount of the code will be modified.
In that case, the tabs shall be eliminated from the entire module in a distinct version control step.
This is because a side effect of eliminating tabs is the loss of difference tracking capability in the version control system. It is thus valuable to separate the code changes from the white space changes. Enforcement: The absence of the tab character in new or modified code shall be confirmed via an automated scan at each build.
Whenever possible, all source code lines shall end only with the single character LF 0x0A. One such problem is associated with multi-line preprocessor macros on Unix platforms.
In addition, an automated tool shall scan all new or modified source code files during each build, replacing each CR-LF sequence with an LF. All module names shall consist entirely of lowercase letters, numbers, and underscores. No spaces shall appear within the file name.