-
Notifications
You must be signed in to change notification settings - Fork 2.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Propose Documentation for Software Best Practices, Coding Conventions, and Style #1504
Merged
andy31415
merged 2 commits into
project-chip:master
from
gerickson:user/gerickson/github-issue-335
Jul 9, 2020
Merged
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,276 @@ | ||
[.text-center] | ||
= Project Connected Home over IP Software | ||
:toc: macro | ||
:toclevels: 7 | ||
:sectnumlevels: 7 | ||
:sectanchors: | ||
:sectlinks: | ||
|
||
:plusplus: ++ | ||
|
||
:sectnums!: | ||
|
||
== Best Practices, Coding Conventions, and Style | ||
|
||
[.text-center] | ||
_Revision 1_ + | ||
_2020-07-08_ | ||
|
||
[.text-center] | ||
*Status:* [red]*Draft* / [red]*Active* | ||
|
||
toc::[] | ||
|
||
== Typographic and Syntactic Conventions | ||
|
||
The following syntactic conventions are used throughout this document: | ||
|
||
_shall_:: | ||
|
||
is used to indicate a mandatory rule or guideline that must be adhered | ||
to without exception to claim compliance with this specification. | ||
|
||
_should_:: | ||
|
||
is used to indicate a rule or guideline that serves as a strong | ||
preference to suggested practice and is to be followed in the absence of | ||
a compelling reason to do otherwise. | ||
|
||
_may_:: | ||
|
||
is used to indicate a rule or guideline that serves as a reference to | ||
suggested practice. | ||
|
||
== Introduction | ||
|
||
There are likely as many unique combinations of software engineering and | ||
development standards, conventions, and practices as there organizations | ||
that do such work. This document pulls together those that Project | ||
Connected Home over IP believes best for our organization, its efforts, | ||
and products that consume those efforts, with a particular emphasis on | ||
embedded systems with C or C{plusplus} language development and runtime | ||
environments. | ||
|
||
This document and requirements should be considered canonical for all | ||
Project Connected Home over IP shared infrastructure software, including | ||
both RTOS-based and non-RTOS-based projects on both tightly- and | ||
loosely-constrained system platforms. | ||
|
||
The document is broadly categorized at the highest level into: | ||
|
||
* Best Practices and Conventions | ||
* Format and Style | ||
|
||
And, within conventions, further sub-categorized into those that apply | ||
to: | ||
|
||
* Tightly-constrained | ||
* Loosely-constrained | ||
|
||
system platforms. Applicability to tightly-constrained systems also | ||
generally applies to shared infrastructure software that is used on both | ||
tightly- and loosely-constrained systems. | ||
|
||
link:#id.jzphr1iiku89[Figure 1 below] attempts to illustrate both | ||
qualitative and quantitative applicability of these guidelines to | ||
Project Connected Home over IP software. | ||
|
||
Generally, product-specific applications have the greatest flexibility | ||
and latitude in applying these guidelines to their software. Whereas, | ||
shared infrastructure bears the least flexibility and bears the greatest | ||
adherence to these guidelines. | ||
|
||
image:CODING_STYLE_GUIDE-figure1.png[Figure 1. Graphical summary of the | ||
qualitative and quantitative applicability to Project CHIP software.] | ||
|
||
[[id.jzphr1iiku89]] | ||
|
||
[.text-center] | ||
*Figure 1.* Graphical summary of the qualitative and quantitative | ||
applicability to Project CHIP software. | ||
|
||
:sectnums: | ||
|
||
== Standards | ||
|
||
Project CHIP embedded software development adopts the minimum C and C{plusplus} | ||
standards listed in Table 2.1 below. | ||
|
||
[[t.4d8bfeef046f29261fc72f1a903d6d10a909957a]][[t.2]] | ||
|
||
[cols=3,options="header"] | ||
|=== | ||
|Language |Minimum Standard |Aliases | ||
|
||
|C|ISO9899:1999|ISO C99, C99 | ||
|C{plusplus}|ISO14882:2011|ISO C{plusplus}11, C{plusplus}11 | ||
|=== | ||
[.text-center] | ||
*Table 2.1.* C and C{plusplus} language minimum standards adopted by Project CHIP | ||
software. | ||
|
||
Product-specific software may elect to use later standards to the extent | ||
their software is not broadly shared inside or outside Project CHIP. | ||
|
||
=== C | ||
|
||
Project CHIP embedded software development uses and enforces the | ||
ISO9899:1999 (aka ISO C99, C99) C language standard as the minimum. | ||
|
||
Wherever possible, particularly in non-product-specific, | ||
shared-infrastructure software, toolchain-specific (e.g GCC/GNU) | ||
extensions or the use of later standards shall be avoided or shall be | ||
leveraged through toolchain-compatibility preprocessor macros. | ||
|
||
==== Motivation and Rationale | ||
|
||
At the time of this writing, the C99 standard has been out for over 20 | ||
years. Project CHIP and both the new and contributed source code that | ||
comprise it have only existed for the last seven to eight of those | ||
20-plus years. | ||
|
||
This is beyond more than adequate time for this standard to be pervasive | ||
throughout any toolchain vendor’s C compiler and saves team members from | ||
worrying about ISO9899:1990 (aka ISO C90, C90) portability issues that | ||
have long-since been solved by C99. | ||
|
||
=== C{plusplus} | ||
|
||
Project CHIP embedded software development uses the ISO14882:2011 (aka | ||
ISO C{plusplus}11) language standard as a baseline for source code | ||
compatibility. Conformance with other standards, for example, ISO14882:1998 | ||
(aka ISO C{plusplus}98), may be additionally required in cases where wider | ||
portability is necessary, but in all cases, ISO C{plusplus}11 is the baseline | ||
requirement. | ||
|
||
Wherever possible, particularly in non-product-specific, | ||
shared-infrastructure software, toolchain-specific (e.g GCC/GNU) | ||
extensions or the use of later standards shall be avoided or shall be | ||
leveraged through toolchain-compatibility preprocessor macros. | ||
|
||
==== Motivation and Rationale | ||
|
||
At the time of this writing, the C{plusplus}11 standard has been out for over | ||
seven years in one form or another and has been twice supplanted, once | ||
by C{plusplus}14 and again by C{plusplus}17. Project CHIP and the source code it has | ||
produced are nearly concurrent with C{plusplus}11. | ||
|
||
This is beyond more than adequate time for this standard to be pervasive | ||
throughout any toolchain vendor’s C{plusplus} compiler and saves team members | ||
from worrying about portability issues that have long-since been solved | ||
by C{plusplus}11. | ||
|
||
By contrast, ISO14882:2014 (aka ISO C{plusplus}14, C{plusplus}14) and ISO14882:2017 (aka | ||
ISO C{plusplus}17, C{plusplus}17), are still insufficiently broad and pervasive in their | ||
toolchain support to warrant the introduction of dependencies on these | ||
standards across all software. | ||
|
||
Note, that while C{plusplus}11 is the C{plusplus} language bar, per Figure 1, embrace of | ||
C{plusplus}11 language- and library-specific features should be approached | ||
thoughtfully and carefully, depending on the deployment context. A | ||
loosely-constrained embedded Linux or Darwin application may want a | ||
broad embrace of C{plusplus}11 language and library features whereas a | ||
tightly-constrained piece of shared infrastructure may want to eschew | ||
C{plusplus}11 entirely or conditionally depend on language-specific features, | ||
where appropriate. | ||
|
||
That said, suitable portability mnemonics, for example, via the C | ||
preprocessor should be used where possible and appropriate to maximize | ||
code portability, particularly for shared embedded product software. An | ||
example of such a portability mnemonic is shown in Listing 2.1 below. | ||
|
||
[source,C] | ||
---- | ||
#ifdef __cplusplus | ||
# if __cplusplus >= 201103L | ||
# define __chipFINAL final | ||
# else | ||
# define __chipFINAL | ||
# endif | ||
#else | ||
#define __chipFINAL | ||
#endif | ||
---- | ||
[.text-center] | ||
*Listing 2.1.* Using the C preprocessor to provide a portability mnemonic | ||
for the C{plusplus}11 and later final keyword. | ||
|
||
== Conventions and Best Practices | ||
|
||
=== Common | ||
|
||
The following sections summarize those best practices that are | ||
independent of particular nuances of either the C or C{plusplus} languages. | ||
|
||
==== When in Rome | ||
|
||
The most important convention and practice in the Project CHIP embedded | ||
software is "_When in Rome..._", per the quote below. | ||
|
||
[quote, St. Ambrose] | ||
____ | ||
If you should be in Rome, live in the Roman manner; if you should be | ||
elsewhere, live as they do there. | ||
____ | ||
|
||
===== Motivation and Rationale | ||
|
||
At this stage in the work group’s and the team’s life cycle, it is rare | ||
the project or subsystem that is entirely new and built from scratch. | ||
More often than not, development will involve extending, enhancing, and | ||
fixing existing code in existing projects. | ||
|
||
When in this situation, it is mandatory you observe how things are done | ||
in this context and do the best that you can to follow the prevailing | ||
conventions present. Not doing so can lead to readability and | ||
maintenance problems down the line and will likely earn you the | ||
disapprobation of the code’s _owner_ or other team members. | ||
|
||
Your extensions or fixes to existing code should be *indistinguishable*, | ||
stylistically, from the original code such that the only way to | ||
ascertain ownership and responsibility is to use the source code control | ||
system’s change attribution (aka _blame_) feature. | ||
|
||
If you find the conventions so foreign or otherwise confusing, it may be | ||
best to let whoever owns the file make the necessary changes or seek the | ||
counsel of others in the group to find out what the right thing to do | ||
is. Never just start changing code wholesale for personal reasons | ||
without consulting others first. | ||
|
||
:sectnums!: | ||
|
||
== Recommended Reading | ||
|
||
While the following references and reading are not part of the formal | ||
best practices, coding conventions, and style cannon, they are | ||
informative and useful guides for improving the style and quality of the | ||
code you write: | ||
|
||
. Jet Propulsion Laboratory. | ||
http://lars-lab.jpl.nasa.gov/JPL_Coding_Standard_C.pdf[JPL | ||
Institutional Coding Standard for the C Programming Language.] Version | ||
1.0. March 3, 2009. | ||
. Jet Propulsion Laboratory. | ||
http://pixelscommander.com/wp-content/uploads/2014/12/P10.pdf[The | ||
Power of Ten – Rules for Developing Safety Critical Code]. December | ||
2014. | ||
. Meyers, Scott. Effective C{plusplus}: 55 Specific Ways to Improve Your | ||
Programs and Designs. Third Edition. 2005. | ||
. Meyers, Scott. More Effective C{plusplus}: 35 New Ways to Improve Your | ||
Programs and Designs. 1996. | ||
. Meyers. Scott. https://www.artima.com/shop/effective_cpp_in_an_embedded_environment[Effective C{plusplus} in an Embedded Environment]. 2015. | ||
. Motor Industry Software Reliability Association. Guidelines for the | ||
Use of the C Language in Critical Systems. March 2013. | ||
. Motor Industry Software Reliability Association. Guidelines for the | ||
Use of the C{plusplus} Language in Critical Systems. June 2008. | ||
|
||
== Revision History | ||
|
||
[cols="^1,^1,<2,<3",options="header"] | ||
|=== | ||
|Revision |Date |Modified By |Description | ||
|1 |2020-07-08 |Grant Erickson |Initial revision. | ||
|=== | ||
|
||
[.text-center] | ||
_Project Connect Home over IP Public Information_ |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not sure that we should say that C++ is required, and straight C is not ok? (Maybe I'm reading this diagram incorrectly).
Maybe we can just remove this diagram, and/or make C allowed in all boxes?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Updated the diagram to show / allow C/C++ in C++ contexts.