Style guide purge + finalize style conventions+ CONTRIBUTING.md document

[rfairley]

Describe the feature

From the maintenance tracker comment (#121):

Style purge—revise the programming style guide to make it much shorter. Make the focus on writing code that has a consistent look and feel, then purge all our code to follow these look and feel rules (maybe via an automated tool...?)

Adding a CONTRIBUTING.md (or other name) document in the top level directory of the respository might help make it more visible too.

Timeline Last week of January - have discussion at team meeting to show proposed changes and get feedback First week of February, before next "release" - merge

Additional information Requires discussion with team to agree on it and get feedback (ideally 1 week before intending to merge these changes).

[rfairley]

Also from maintenance tracker which we can handle here:

Decide on file name and namespace conventions Reason: Better to have this style be more consistent

[rfairley]

Some widely-used style guides and standards where we can get inspiration:

• CoreGuidelines: https://github.com/isocpp/CppCoreGuidelines (I think this has some good tips in general e.g. https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#p5-prefer-compile-time-checking-to-run-time-checking)
• AUTOSAR: https://www.autosar.org/fileadmin/user_upload/standards/adaptive/17-03/AUTOSAR_RS_CPP14Guidelines.pdf (linked before by @tygamvrelis )
• MISRA (FreeRTOS follows this https://www.freertos.org/FreeRTOS-Coding-Standard-and-Style-Guide.html)
• Google's: https://google.github.io/styleguide/cppguide.html

Tools that implement checks for style:

• clang-format https://clang.llvm.org/docs/ClangFormat.html (this could be useful for CI, it looks like it has different options for the checks to perform)

Overall we should reference a format from here https://en.wikipedia.org/wiki/Indentation_style (we've just used K&R up to now).