{"type":"doc","content":[{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"378e5bf6-9ab3-4b38-a0d8-893844f12e69"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"1992dcb2-756a-4380-9619-34a141358dc6"}},{"type":"rule"},{"type":"heading","attrs":{"level":1},"content":[{"text":"Embedded C Coding Standards","type":"text"}]},{"type":"paragraph","content":[{"text":"Coding standards help keep the code clean, and consistent. The guidelines below also explain and cite the reasons why we should follow them, and certain ones will have references to ISO26262, which is a safety certification guideline for code.","type":"text"}]},{"type":"paragraph","content":[{"text":"Goals","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Consistency","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Promote ","type":"text"},{"text":"Best Practices","type":"text","marks":[{"type":"link","attrs":{"href":"https://sibros.atlassian.net/wiki/spaces/SF/pages/62652558/C+Coding+Standards#Best-Practices"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Provide ","type":"text"},{"text":"Structure","type":"text","marks":[{"type":"strong"}]},{"text":" to the code","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoid bugs and increase developer efficiency","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Optimize for code reviewers and readers ","type":"text"},{"text":"rather than code developers","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"paragraph","content":[{"text":"Non-Goals","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Nitpick on the developer code","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Argue whitespace issues (","type":"text"},{"text":"clang-format","type":"text","marks":[{"type":"code"}]},{"text":" auto formats brace positions and spaces)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Any code you write, modify or generate should follow the coding standards. If you find any code that doesn't follow these rules, please take the initiative to fix it.","type":"text"}]},{"type":"paragraph","content":[{"text":"Follow the Boy Scout Rule","type":"text","marks":[{"type":"strong"}]}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Leave the campground cleaner than you found it.","type":"text"}]}]},{"type":"rule"},{"type":"heading","attrs":{"level":1},"content":[{"text":"Principles","type":"text"}]},{"type":"paragraph","content":[{"text":"Principles are guiding rules to be more successful. You need to constantly keep these in mind and have them serve as a guardrail to keep you focused towards writing good, and clean software.","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"You should not learn of the following principles once and then forget them. A principle is a kind of rule, belief, or idea that guides you.","type":"text"}]},{"type":"paragraph","content":[{"text":"[Clean C++]","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"KISS","type":"text"}]},{"type":"rule"},{"type":"paragraph","content":[{"text":"Keep It Simple and Stupid","type":"text","marks":[{"type":"code"}]},{"text":" and less obscure. Keep the logic as simple as possible, and oftentimes as un-optimized as possible. ","type":"text"},{"text":"Aim for code readability over creating fancy logic.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Very cool macro but could be deadly:","type":"text"}]},{"type":"codeBlock","content":[{"text":"#define CRITICAL_SECTION() \\\n for (int i = ISR_disable() | 1; i != 0; i=ISR_enable() & 0)\n\nCRITICAL_SECTION() {\n ++x;\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Violation of the ","type":"text"},{"text":"KISS","type":"text","marks":[{"type":"code"}]},{"text":" principle in an effort to \"optimize\":","type":"text"}]},{"type":"codeBlock","content":[{"text":"uint8_t array[64];\n\n// Do not do this\nfor (uint32_t i = 0; i < 64/8; i++) {\n *(uint64_t*)&array[i] = 0;\n}\n\n// Apply the KISS principle\nuint8_t array[64] = { 0 };","type":"text"}]},{"type":"paragraph","content":[{"text":"Aim for extreme simplicity and write minimal amount of code. And remember my wise words:","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"It is not about how many lines of code you write, it is about how few.","type":"text"}]},{"type":"paragraph","content":[{"text":"-- Lockheed Martin (Preet)","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"DRY","type":"text"}]},{"type":"rule"},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Copy and paste is a design error.","type":"text"}]},{"type":"paragraph","content":[{"text":"-- David L. Parnas","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Do not Repeat Yourself","type":"text","marks":[{"type":"code"}]},{"text":" The extent of this even means ","type":"text"},{"text":"not repeating yourself in comments","type":"text","marks":[{"type":"strong"}]},{"text":". In general, whenever you believe a change in logic requires you to make the same fix somewhere else, then it is time to refactor the logic to avoid repeating yourself.","type":"text"}]},{"type":"paragraph","content":[{"text":"Do not repeat yourself in comments either","type":"text"}]},{"type":"codeBlock","content":[{"text":"// The timeout is set to 100ms because ...\nconst uint32_t timeout_ms = 100;\n\n// Instead, do this:\n\n// The timeout value is chosen because ...\nconst uint32_t timeout_for_can_message_ms = 100;","type":"text"}]},{"type":"paragraph","content":[{"text":"But apart from this silly example, do not repeat your code in multiple places. Instead, refactor to a common function, and then re-use that. Effects of this includes:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoid updating a bug-fix in multiple places","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Unit-test just one piece of code","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Maintain just one source of truth","type":"text"}]}]}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.","type":"text"}]},{"type":"paragraph","content":[{"text":"-- The Pragmatic Programmer","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"YAGNI","type":"text"}]},{"type":"rule"},{"type":"paragraph","content":[{"text":"You Ain't Gonna Need It","type":"text","marks":[{"type":"code"}]},{"text":" This one is the most occurring theme among developers. We usually develop APIs that we think we will need one day. But the fact of the matter is that we can design the APIs when we really need it.","type":"text"}]},{"type":"paragraph","content":[{"text":"Here is a good one:","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Do not do something today that you can do tomorrow, because tomorrow, you might not need to do it at all.","type":"text"}]},{"type":"paragraph","content":[{"text":"IBM Websphere Group (Preet)","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Prefer to build software when you really need it, otherwise it is a waste. Avoid your impulses:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"I might need it one day","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This will make it better for the future","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"But at the same time, provisioning certain things towards the future is okay. For example, the TCP/IP stack provisioned for some reserved bytes and although the standard is largely unchanged, it did provide the roadway towards IPv6. Another example is that if you are developing a communication standard, it is okay to provision for an extra byte for a ","type":"text"},{"text":"version","type":"text","marks":[{"type":"code"}]},{"text":" that allows you to amend the standard in the future.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Best Practices","type":"text"}]},{"type":"rule"},{"type":"paragraph","content":[{"text":"Here are some general Sibros guidelines for being a good, responsible engineer.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Write code for someone else to take over","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Strong developers never need to worry about ","type":"text"},{"text":"job security","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Pass it on such that you can go do even more exciting work","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Knowledge is not worth anything until transferred","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Take your time, and do things right","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Write code as if you are writing safety critical code for a pacemaker or an airplane flight controller","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This includes unit-test code; write maintainable unit test code","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Apply proper code fixes rather than patches","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Any workarounds are going to come back to haunt you","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Be thorough, and understand your code fixes","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Get to the root cause","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"There is no such thing as magic","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Have a firm definition of ","type":"text"},{"text":"it works","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Can you bet your life on it?","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Will it work 100% of the time?","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Write high quality, deterministic code","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Design code such that you will never need to hit the reset button for 1 year, 10 years, and beyond","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"One Sibros team member's previous colleagues once said ","type":"text"},{"text":"Oh we hit this bug every 24 hours, let's reset our controller every 23 hours","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"They never worked with that person again, and another team member gets angry if they ever mention his name","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Memory allocation should never fail","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Design code such that even if someone attacks your controller through a CAN bus, or Ethernet network, your code will always result in predictable execution","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Work with integrity and honesty","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Treat your co-workers and stakeholders with respect, even when in disagreement","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Communicate concisely and ensure criticism and comments are constructive","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Don't be afraid to give honest feedback, and continue to iterate and improve on your work","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Start with establishing a good base for your header file before writing your code","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"All parties can work together to come up with a solution before implementing any code; more ideas are always better!","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Reviewing the header file first clarifies any issues with ticket requirements or misunderstandings","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This also prevents wasted time developing code, tests and debugging said code that may end up being deleted","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Modularize Code","type":"text"}]},{"type":"paragraph","content":[{"text":"Modularize code, and do not create ","type":"text"},{"text":"God Objects","type":"text","marks":[{"type":"code"}]},{"text":". When you are dealing with a large problem, split the problem into smaller code modules and make the code only do one thing. This allows for the module to be implemented with simple logic thus improving the overall code readability as well as making it easier to test.","type":"text"}]},{"type":"paragraph","content":[{"text":"If we are creating an HTTP client, do not put all the code into a single module. Instead, consider splitting this problem into small code blocks, such as:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A socket library to read the data","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A buffer module that the data is read onto","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"An HTTP parser library to parse the incoming data","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Reference ","type":"text"},{"text":"this article","type":"text","marks":[{"type":"link","attrs":{"href":"https://gitlab.com/sibros_public/public/wikis/c/code_designs#code-modularization"}}]},{"text":" for further inspiration.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Functions","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Write Testable Code","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Write code with the test code alongside. This is hard to capture in a guideline like this coding standards' document, but design code that is modular, and testable. Refer to the ","type":"text"},{"text":"C Unit Test Tutorial","type":"text","marks":[{"type":"link","attrs":{"href":"https://gitlab.com/sibros_public/public/-/wikis/c/Unit-Testing-for-C"}}]},{"text":" for more details.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Keep the functions small","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not write functions that are ","type":"text"},{"text":"larger than 10 lines of meaningful code","type":"text","marks":[{"type":"strong"}]},{"text":". The benefits are:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Creates smaller units of code that are easier to test","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Increases code clarity","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Decreases code complexity (ISO26262, Table 1: 1A)","type":"text"}]}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not use more than 5 brace levels in your code","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Refactor code into smaller functions","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Re-structure the branch statements to reduce the curly brace nesting","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This improves the overall readability of the code","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No recursive functions","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In Embedded Systems, the stack memory is precious, as there is usually not very much.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Each function should only have one return statement","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"and that should be at the end of the function. This is to prevent unintentional side-effects where a developer adds some code thinking it will be run, but the function exits out before it gets to that piece of code.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"MISRA and safety certified code requires this","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text","marks":[{"type":"strong"}]},{"text":"(void)","type":"text","marks":[{"type":"code"}]},{"text":" for functions without inputs","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A function with no input should be labeled as ","type":"text"},{"text":"func(void)","type":"text","marks":[{"type":"code"}]},{"text":" for the parameters. This is because if you omit the void in C, you can pass it infinite number of parameters. C++ safeguards you for this case though.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Prefer at most 10 meaningful lines per function","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This forces you to make the code more modular","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This helps during unit-testing","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoid using more than 5 ","type":"text"},{"text":"{}","type":"text","marks":[{"type":"code"}]},{"text":" brace levels in your code","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text","marks":[{"type":"strike"}]},{"text":"Yoda notation","type":"text","marks":[{"type":"strike"},{"type":"strong"},{"type":"link","attrs":{"href":"https://knowthecode.io/yoda-conditions-yoda-not-yoda"}}]},{"text":" in equality checks but not anywhere else.","type":"text","marks":[{"type":"strike"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: Use ","type":"text","marks":[{"type":"strike"}]},{"text":"if (5 == value)","type":"text","marks":[{"type":"code"}]},{"text":" instead of ","type":"text","marks":[{"type":"strike"}]},{"text":"if (value == 5)","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: Use ","type":"text","marks":[{"type":"strike"}]},{"text":"if (const_x != value)","type":"text","marks":[{"type":"code"}]},{"text":" instead of ","type":"text","marks":[{"type":"strike"}]},{"text":"if (value != const_x)","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: Do not use","type":"text","marks":[{"type":"strike"}]},{"text":" ","type":"text"},{"text":"if (5 < value)","type":"text","marks":[{"type":"code"}]},{"text":"; see ","type":"text","marks":[{"type":"strike"}]},{"text":"Yoda notation","type":"text","marks":[{"type":"strike"},{"type":"strong"},{"type":"link","attrs":{"href":"https://knowthecode.io/yoda-conditions-yoda-not-yoda"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: Do not use","type":"text","marks":[{"type":"strike"}]},{"text":" ","type":"text"},{"text":"if (10 >= value)","type":"text","marks":[{"type":"code"}]},{"text":"; see ","type":"text","marks":[{"type":"strike"}]},{"text":"Yoda notation","type":"text","marks":[{"type":"strike"},{"type":"strong"},{"type":"link","attrs":{"href":"https://knowthecode.io/yoda-conditions-yoda-not-yoda"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Because we don't want to accidentally assign the variable in the condition check.","type":"text","marks":[{"type":"strike"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Even though static analysis should catch this, we do not want to rely on it.","type":"text","marks":[{"type":"strike"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"PCLint currently detects and fails on accidental assignment in condition for both C and C++, so Yoda notation is no longer required (but still recommended)","type":"text","marks":[{"type":"strong"}]}]}]}]}]}]},{"type":"codeBlock","content":[{"text":"if (constant == my_variable) { } // Good\n\nif (my_variable == constant) { } // Bad\n\nif (constant != my_variable) { } // Good\n\nif (my_variable != constant) { } // Bad","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"const","type":"text","marks":[{"type":"code"}]},{"text":" type qualifier on pointer parameters when applicable (i.e. when the referenced value remains unchanged).","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not use this type qualifier on pass-by-value parameters as it is redundant.","type":"text"}]}]}]}]}]},{"type":"codeBlock","content":[{"text":"const char *app__get_log_line(const *module_s); // Good \nbool app__is_id_ready(const *module_s, const size_t type_id); // Bad, const type_id is redundant","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Validate Pointers","type":"text"}]},{"type":"paragraph","content":[{"text":"Assuming there is a heavy use of pointers, we want to balance the fundamental checks with those that may actually be useful and create a safer code-base.","type":"text"}]},{"type":"paragraph","content":[{"text":"C code modules are designed based on ","type":"text"},{"text":"structs","type":"text","marks":[{"type":"code"}]},{"text":" and the instances of these structs are then given to APIs. This mimics how C++ classes operate as the first parameter to functions is the module pointer itself which C++ refers to as the ","type":"text"},{"text":"this pointer","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"codeBlock","content":[{"text":"typedef struct {\n void * data;\n} my_module_s;\n\nvoid my_module__api(my_module_s *this_ptr);","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Validate and check all pointers being passed into public API","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"We used to avoid this, but had to revert our decision based on safety certified code requirements. It introduced extra brace level and increased cyclomatic complexity, but it was necessary, and hence the next bullet point is striked-out.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not check the ","type":"text","marks":[{"type":"strike"}]},{"text":"this","type":"text","marks":[{"type":"code"}]},{"text":" pointer equivalent of C++ with ","type":"text"},{"text":"NULL","type":"text","marks":[{"type":"code"}]},{"text":". This creates a lot of fluff, creates potential waste that will only be rarely useful because it is a programming error to pass ","type":"text"},{"text":"NULL","type":"text","marks":[{"type":"code"}]},{"text":" pointers and we cannot be over-protective about this condition.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Private functions of the module can omit additional pointer checks as long as you can ensure through unit-testing that those pointers could never be bad memory pointers","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The rest of the pointers ","type":"text"},{"text":"should","type":"text","marks":[{"type":"strong"}]},{"text":" be checked and ","type":"text"},{"text":"design code such that error conditions will not end up in a CPU exception","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"There may be reasons for not checking the ","type":"text"},{"text":"this_ptr","type":"text","marks":[{"type":"code"}]},{"text":", however, the safety aspects of the code outweigh the benefits. Here are some downsides that we did assess though:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Unit-tests double since each method needs a test for the ","type":"text"},{"text":"NULL","type":"text","marks":[{"type":"code"}]},{"text":" pointer","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Each function would have additional brace level (early returns are forbidden due to MISRA/C)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"We (used to) consider passing a ","type":"text"},{"text":"NULL","type":"text","marks":[{"type":"code"}]},{"text":" pointer as a user error, and do not believe it adds significant value","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":"void my_api(module_s *this_ptr, void *ptr) {\n if (NULL != this_ptr) {\n // Ensure that bad pointers do not execute an un-deterministic instruction\n if (NULL != ptr) { \n }\n }\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pointer Validation Recommendation","type":"text"}]},{"type":"paragraph","content":[{"text":"Each pointer must be validated, and there are certain rules to follow in order to get past static analysis tools flagging your code, and preventing it from getting merged.","type":"text"}]},{"type":"codeBlock","content":[{"text":"// DO NOT DO THIS\n// CERT C will flag this as 'warning 613: potential use of null pointer\nvoid foo(module_s *module, void *pointer) {\n const bool pointers_are_valid = (NULL != module) && (NULL != pointer);\n\n if (pointers_are_valid) {\n // ...\n }\n}\n\n// Explicitly check pointers\nvoid foo(module_s *module, void *pointer) {\n if ((NULL != module) && (NULL != pointer)) {\n // ...\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"If there are \"private\" (or static) functions, they do not need redundant checks as long as code structure guarantee that they will never be called unsafely. These are \"forgiven\" by PCLint or CERTC as long as they follow the coding standards of containing ","type":"text"},{"text":"__private_","type":"text","marks":[{"type":"code"}]},{"text":" name. Here is an example:","type":"text"}]},{"type":"codeBlock","content":[{"text":"static void module__private_do(module_s *module, void *pointer) {\n // No need to check 'if ((NULL != module) && (NULL != pointer))'\n}\n\nvoid module__do(module_s *module, void *pointer) {\n if ((NULL != module) && (NULL != pointer)) {\n module__private_do(module, pointer);\n }\n}","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Variables","type":"text"}]},{"type":"paragraph","content":[{"text":"Do not re-use variables, and avoid changing the variables passed as copy. You can opt to make the parameters ","type":"text"},{"text":"const","type":"text","marks":[{"type":"code"}]},{"text":" to enforce this.","type":"text"}]},{"type":"codeBlock","content":[{"text":"sl_buffer_s sl_buffer__init(void *static_memory, size_t memory_size_bytes) {\n memory_size_bytes = (NULL == static_memory) ? 0U : memory_size_bytes;\n}\n\n// Do this instead\nsl_buffer_s sl_buffer__init(void *static_memory, size_t memory_size_bytes) {\n const size_t sanity_checked_memory_size_bytes = (NULL == static_memory) ? 0U : memory_size_bytes;\n}","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Data Initialization","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Globals","type":"text"}]},{"type":"paragraph","content":[{"text":"C standards call for initialization of all global memory to zero, and therefore, there is no need for explicit initialization. For any customer integration that fails to do this, we need to work with them to make sure that their startup code performs this necessary step.","type":"text"}]},{"type":"codeBlock","content":[{"text":"int my_global;\nstruct_s my_struct;","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Structs","type":"text"}]},{"type":"paragraph","content":[{"text":"Initialize the members by name. Use colon for C++ (it doesn’t support C dot initializer)","type":"text"}]},{"type":"paragraph","content":[{"text":"Example","type":"text"}]},{"type":"codeBlock","content":[{"text":"const ecu_spi__channel_config_s ecu_spi__channel_configs[ECU_SPI__CHANNEL_COUNT] = {\n [ECU_SPI__CHANNEL_MOTOR] = { .master = true, .timing = FALLING_EDGE},\n [ECU_SPI__CHANNEL_HSD] = { .master = false, .timing = FALLING_EDGE},\n [ECU_SPI__CHANNEL_SBC] = { .master = true, .timing = RISING_EDGE},\n};","type":"text"}]},{"type":"paragraph","content":[{"text":"For consistency reasons, when the dot initializer is not possible, then always use ","type":"text"},{"text":"sl_utils__memset_zero()","type":"text","marks":[{"type":"code"}]},{"text":", then set the selected (or all) members appropriately.","type":"text"}]},{"type":"codeBlock","content":[{"text":"void zero_struct_using_ptr(struct_s *s) {\n sl_utils__memset_zero(s, sizeof(*s));\n\n // Then\n s->foo = 1;\n}\n\nvoid instantiate_struct() {\n struct_s s;\n sl_utils__memset_zero(&s, sizeof(s));\n\n // Then\n s.foo = 1;\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"The reasons to use ","type":"text"},{"text":"sl_utils__memset_zero()","type":"text","marks":[{"type":"code"}]},{"text":" is that:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The notation ","type":"text"},{"text":"*s = (struct_s) { }","type":"text","marks":[{"type":"code"}]},{"text":" is not portable because some compilers may complain about empty ","type":"text"},{"text":"{ }","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"memset()","type":"text","marks":[{"type":"code"}]},{"text":" may be used but it creates possibility of bugs because the parameters of this function may be swapped easily","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Note that ","type":"text"},{"text":"bzero()","type":"text","marks":[{"type":"code"}]},{"text":" is not recommended since it has been deprecated","type":"text"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"Do not confuse the struct initialization with array initialization which can use ","type":"text"},{"text":"= {0}","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"char array[2] = {0}","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Arrays/Maps","type":"text"}]},{"type":"paragraph","content":[{"text":"For constant arrays that map two sets of values and should contain a certain number of elements, use a static, compile-time assertion macro to validate the array size.","type":"text"}]},{"type":"paragraph","content":[{"text":"This ensures that the code will only compile when the number of elements in the map/array equals the number that is expected.","type":"text"}]},{"type":"paragraph","content":[{"text":"Example For an array that maps enums to strings:","type":"text"}]},{"type":"codeBlock","content":[{"text":"static const sl_string_value_map_s image_type_string_map[] = {\n {\"BOOTLOADER\", SL_ECU_INFO__IMAGE_TYPE_BOOTLOADER},\n {\"APP\", SL_ECU_INFO__IMAGE_TYPE_APP},\n {\"UPDATER\", SL_ECU_INFO__IMAGE_TYPE_UPDATER},\n {\"CALIBRATION_BLOCK\", SL_ECU_INFO__IMAGE_TYPE_CALIBRATION_BLOCK},\n};","type":"text"}]},{"type":"paragraph","content":[{"text":"Consider adding the following compile-time assertion:","type":"text"}]},{"type":"codeBlock","content":[{"text":"COMPILE_TIME_ASSERT((size_t)SL_ECU_INFO__IMAGE_TYPE_COUNT == ARRAY_COUNT(image_type_string_map));","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Safety and MISRA","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No unreacheable code","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"You should not be able to do this at Sibros code base because of enforcement of 100% test coverage","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No dead code","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not leave commented code base that is not used in production","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No recursive functions","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"In Embedded Systems, the stack memory is precious, as there is usually not very much.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No dynamic memory allocation (MISRA C:2004, 20.4)","type":"text","marks":[{"type":"strong"}]},{"text":" i.e. you are not allowed to use malloc and free as it can cause unintended issues when functions such as malloc are unable to provide a valid memory location.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No continue or goto statements (MISRA C:2012, 15.1)","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"Because even the compiler itself cannot prevent stack corruption for this code:","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":" goto jump_over;\n int stack_corruption = 0;\n\n jump_over:\n stack_corruption = 123; // Oops, this was not allocated on the stack","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Switch Statements","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"There should always be a default in the switch case. The default shall be the last statement in the switch block","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Switch statements containing fall-through blocks require explicit comment acknowledging the intentional fall-through. To automate this, there is a ","type":"text"},{"text":"FALL_THROUGH_SWITCH_CASE","type":"text","marks":[{"type":"code"}]},{"text":" macro in ","type":"text"},{"text":"sl_common.h","type":"text","marks":[{"type":"code"}]},{"text":" that should be used to signal this intent.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Initialize all local variables","type":"text","marks":[{"type":"strong"}]},{"text":" - empty pointers should be initialized to ","type":"text"},{"text":"NULL","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Initialize arrays using: ","type":"text"},{"text":"int array[3] = { 0 };","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not do this:","type":"text"},{"type":"hardBreak"},{"text":"int array[3] = { };","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Prefer defining consts using this approach which is part of ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"const uint32_t VALUE = UINT32_C (800000);","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoid doing this though: ","type":"text"},{"text":"UINT32_C(2 * 2)","type":"text","marks":[{"type":"code"}]},{"text":" because this macro simply concatenates ","type":"text"},{"text":"UL","type":"text","marks":[{"type":"code"}]},{"text":" or similar based on the machine and the result of an operation occurring inside of the macro parameter may not be deterministic","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use parentheses to make code clear and explicit.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not do: ","type":"text"},{"text":"if a > b + c || d < e","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Instead do: ","type":"text"},{"text":"if ( (a > (b + c)) || (d < e) )","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Conditional Operators ","type":"text"},{"text":"Even one line statements should have curly brackets","type":"text","marks":[{"type":"strong"}]},{"text":" Example:","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":" if (door_open) { \n door_open = false; \n }","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"if","type":"text","marks":[{"type":"code"}]},{"text":" statements should always have an ","type":"text"},{"text":"else","type":"text","marks":[{"type":"code"}]},{"text":" statement if there is an ","type":"text"},{"text":"else if","type":"text","marks":[{"type":"code"}]},{"text":" statement. The ","type":"text"},{"text":"else","type":"text","marks":[{"type":"code"}]},{"text":" statements help explicit indicate that we have thought about that situation and decided that no work needs to be done there. The compiler is smart and will optimize this code out anyway, so no need to worry that this takes code space. Pattern:","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":" if (condition) { \n // insert code here \n } else if (second_condition) {\n // insert some more code \n } else { \n }","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No unary operator if pre or post increment can alter the behavior of the code. Using these operators where there is only the increment or decrement operation is taking place is okay.","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":" // Do not do this\n *p++ = 1;\n byte[counter++] = 123;\n int b = a++;\n int c = ++a;\n if (++a > 5)\n if (a++ > 5)\n while (a++ > 6)\n\n // This is okay\n int okay = 5;\n okay++;\n okay = okay + 1;\n okay += 1;\n ++okay;","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"There should be no commented out code in the code base.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No ","type":"text"},{"text":"#if 0","type":"text","marks":[{"type":"code"}]},{"text":" blocks","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No block comments that disable code (source control is your friend)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This improves the readability of you code and reduces the amount of unnecessary code in the code base.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Unsigned numbers should have ","type":"text"},{"text":"U","type":"text","marks":[{"type":"code"}]},{"text":" at the end. Example: ","type":"text"},{"text":"42U","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Unsigned long numbers should have ","type":"text"},{"text":"UL","type":"text","marks":[{"type":"code"}]},{"text":" at the end. Example: ","type":"text"},{"text":"56UL","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not write obfuscated 'smart' code - saving on the microseconds of processor time (or not even that) is not worth the headache of trying to understand someone else's tricky code which can take a long time and also be error prone.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use static const in place of const for local variables:","type":"text","marks":[{"type":"strike"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Latest decision:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"static","type":"text","marks":[{"type":"code"}]},{"text":" local variables are not allowed according to ","type":"text"},{"text":"Module Design","type":"text","marks":[{"type":"link","attrs":{"href":"https://sibros.atlassian.net/wiki/spaces/SP/pages/101777636/Embedded+C+Coding+Standards#Module-Design"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This rule caused confusion on the use of ","type":"text"},{"text":"static const","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The benefit of variable data construction outweighs the cost of explanation of this rule","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Obsolete decision:","type":"text","marks":[{"type":"strike"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"For local variables, avoid using: ","type":"text","marks":[{"type":"strike"}]},{"text":"const char foo[] = “bar”","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"const int test = 1","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use","type":"text","marks":[{"type":"strike"}]},{"text":" ","type":"text"},{"text":"static const char foo[] = “bar”","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":"Because if we use just const (without static), the variable will need to be constructed on each entry to the function, and would not only use extra runtime, but also use stack memory.","type":"text","marks":[{"type":"strike"}]}]}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not use the C++ style ","type":"text"},{"text":"Expects( ) and Ensures( )","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Ri-expects"}}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"We want our code to gracefully fail and not run into exceptions that it cannot handle. Whenever there is doubt, always assume you are designing a safety critical controller that is responsible to ensure that a car’s driver would always be able to apply the brakes correctly on the vehicle.","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Documentation","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Code should be self-documenting","type":"text","marks":[{"type":"link","attrs":{"href":"#markdown-header-expressive-code"}}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Although, there may be code such as mathematical formulas that still require a comment to explain the intent of the code. In this case, make sure to write the comment at the time the code is written","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Comments can be used to explain the intent of the code if self-documentation is not sufficient","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Include all separator comment blocks","type":"text","marks":[{"type":"strong"}]},{"text":" (even when there is no content below them) such as:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Defines","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"typedefs","type":"text","marks":[{"type":"code"}]},{"text":" etc.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Please see coding file templates and example structure below","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"/**","type":"text","marks":[{"type":"code"}]},{"text":" to document multi-line comments for Doxygen","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"For consistency, header files (public APIs) should always do this over ","type":"text"},{"text":"/*","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This is for consistency and also because Lint/MISRA does not like multi-line comments using ","type":"text"},{"text":"//","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Documentation is mandatory for public facing interfaces and optional everywhere else.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"Doxygen Tags","type":"text","marks":[{"type":"link","attrs":{"href":"http://www.doxygen.nl/manual/docblocks.html"}}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Doxygen doesn’t like documenting ","type":"text"},{"text":"static inline","type":"text","marks":[{"type":"code"}]},{"text":" functions so do not use them","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This is also discouraged because ","type":"text"},{"text":"inline","type":"text","marks":[{"type":"code"}]},{"text":" functions cannot be mocked during unit-testing, as mentioned previously","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"For consistency, always use only two types","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"/**","type":"text","marks":[{"type":"code"}]},{"text":" style for functions or documentation prior to a construct","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"///< ","type":"text","marks":[{"type":"code"}]},{"text":"for documenting something on the same line","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not mix of ","type":"text"},{"text":"///","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"/**","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The header file looks more consistent this way","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not use ","type":"text"},{"text":"@brief","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"It simply starts a new paragraph.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"It has no effect on the documentation. If you want multiple paragraphs, separate them by an empty line","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not use ","type":"text"},{"text":"@file my_file.h","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Doxygen knows your file's name so follow the ","type":"text"},{"text":"DRY","type":"text","marks":[{"type":"code"}]},{"text":" principle","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If there is no parameter or return type, then do not use ","type":"text"},{"text":"@param none","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"@return none","type":"text","marks":[{"type":"code"}]},{"text":" respectively","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"@param","type":"text","marks":[{"type":"code"}]},{"text":" is only needed for parameter names that are not clear","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If the variable is very clear and explicitly named, there should be no need for explaining the parameter. If someone does still explain the parameter for whatever reason, we don’t need to spend any time pointing it out and/or having them remove the comment or amend their commit (all of which takes more time than just leaving a redundant comment in there).","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoid Comments - comments should only be used if your code itself cannot express the intent.","type":"text"}]}]}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Truth can only be found in one place: the code.","type":"text"}]},{"type":"paragraph","content":[{"text":"-- Robert C. Martin, Clean Code","type":"text"}]}]},{"type":"paragraph","content":[{"text":"This means that the names of the variables and functions etc should describe their purpose instead of having to rely on comments to understand the code. ","type":"text"},{"text":"Spend extra time choosing your variable names, and your goal should be that you do not need to document your APIs.","type":"text","marks":[{"type":"strong"}]},{"text":" Note that in this code sample, we do not need to describe the parameters.","type":"text"}]},{"type":"codeBlock","content":[{"text":"/**\n * Read up to 'bytes' number of bytes into the user provided memory\n * @returns number of bytes consumed\n */\nsize_t sl_data_carrier__consume(sl_data_carrier_s *data_carrier, void *input_buffer, size_t bytes);","type":"text"}]},{"type":"paragraph","content":[{"text":"Here is a bad example","type":"text"}]},{"type":"codeBlock","content":[{"text":"uint32_t sl_crc32__compute(uint32_t crc, const uint8_t *data, size_t size, void (*callback)(void));\n\n// But we can improve this by naming our variables that speak for the code itself\nuint32_t sl_crc32__compute(uint32_t crc_initial_value, const uint8_t *data, size_t data_size_in_bytes,\n void (*callback_during_computation)(void));","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No Redundant comments","type":"text","marks":[{"type":"strong"}]},{"text":" If the code can be read and interpreted, do not repeat that in a comment itself.","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":"// This will call the close method and return\nvoid close_file(file *file) {\n close(file);\n}","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No closing brace comments","type":"text","marks":[{"type":"strong"}]},{"text":" Refactor code such that the braces do not enclose a large block of code and hence there is no need for closing brace comments.","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":"if (...) {\n while (...) {\n }\n} // if","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In general, use comment block style comments (historic c-style) for consistency; ","type":"text"},{"text":"/* comment */","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"There should be absolutely no ","type":"text"},{"text":"TODO","type":"text","marks":[{"type":"code"}]},{"text":" tags in the comments unless accompanied by a Gitlab ticket","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"/*","type":"text","marks":[{"type":"code"}]},{"text":" style comments for multi-line comments (advised by Lint)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"/**","type":"text","marks":[{"type":"code"}]},{"text":" style comment to comment function docstrings (See ","type":"text"},{"text":"Doxygen Comments","type":"text","marks":[{"type":"link","attrs":{"href":"#doxygen"}}]},{"text":")","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not use ","type":"text"},{"text":"/**","type":"text","marks":[{"type":"code"}]},{"text":" style comments for documentation inside of functions (","type":"text"},{"text":"/**","type":"text","marks":[{"type":"code"}]},{"text":" is for Doxygen)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"/**< ","type":"text","marks":[{"type":"code"}]},{"text":"style comments to document struct members on the same line","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Examples of good comments:","type":"text"}]},{"type":"paragraph","content":[{"text":"API documentation (doxygen style):","type":"text"}]},{"type":"codeBlock","content":[{"text":"/**\n * A brief stating the purpose of the function.\n * @param some_parameter Explanation of parameter and it's value range.\n * @return Explanation of what the function returns and expected value range.\n */\nuint32_t my_function(uint32_t some_parameter);\n/** \n * Struct documentation\n */\ntypedef struct {\n int member; /**< Documentation about this member */\n} my_struct_s;","type":"text"}]},{"type":"paragraph","content":[{"text":"Lint exception:","type":"text"}]},{"type":"codeBlock","content":[{"text":"/*lint !e9087 memcpy() requires void *. */","type":"text"}]},{"type":"paragraph","content":[{"text":"Implementation details that may not be obvious to other developers:","type":"text"}]},{"type":"codeBlock","content":[{"text":"void mcu_reset__perform_reset(void) {\n /* Unlock is required before writing to the SCU registers to request reset */\n IfxScuWdt_clearSafetyEndinitInline(IfxScuWdt_getSafetyWatchdogPasswordInline());\n IfxCpu_triggerSwReset();\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Commenting with ticket for future improvement:","type":"text"}]},{"type":"codeBlock","content":[{"text":"void os_system_config__shutdown(os_system__shutdown_reason_e shutdown_reason) {\n (void)shutdown_reason; //TODO #1234: Need to update shared ram\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Comments needing to be resolved before merging:","type":"text"}]},{"type":"paragraph","content":[{"text":"Temporary test code:","type":"text"}]},{"type":"codeBlock","content":[{"text":" // TESTING\n if (main_test.timeout > 0) {","type":"text"}]},{"type":"paragraph","content":[{"text":"An incomplete implementation (resolve before merging, otherwise provide ticket #):","type":"text"}]},{"type":"codeBlock","content":[{"text":"void os_system_config__shutdown(os_system__shutdown_reason_e shutdown_reason) {\n (void)shutdown_reason; //TODO: Need to update shared ram\n}","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Balanced length for variables","type":"text"}]},{"type":"paragraph","content":[{"text":"Keep a balance between variable length and making the intent clear.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Code completion can help","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoid exceeding the line character limit","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not use a very long name such as:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"SL_UDS_SERVICE_SECURITY_ACCESS_DIFFERENCE_BETWEEN_REQUEST_SEED_AND_SEND_KEY","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use this instead:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"SL_UDS_SERVICE_SECURITY_ACCESS_SEED_TO_KEY_OFFSET","type":"text","marks":[{"type":"code"}]}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Avoid magic numbers","type":"text"}]},{"type":"paragraph","content":[{"text":"The definition of a magic number is when a hardcoded constant in code is obscure, and the developer's intent is not clear. In other words, readers may ask why was this specific constant chosen? And, what are the effects if I modify the constant?","type":"text"}]},{"type":"paragraph","content":[{"text":"Developers should avoid magic numbers by ensuring that the ","type":"text"},{"text":"intent","type":"text","marks":[{"type":"strong"}]},{"text":" of any hardcoded constant is clear.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Timeout example","type":"text"}]},{"type":"codeBlock","content":[{"text":"// Good: Timeout is some arbitrary whole unit (1 second)\nconst int tcp_connect_timeout_ms = 1000;\nTCP_connect(&connection, tcp_connect_timeout_ms);\n\n// Bad: This timeout is suspiciously specific\n// Is it derived from a calibration? Or, is it random?\nconst int tcp_connect_timeout_ms = 3655;\nTCP_connect(&connection, tcp_connect_timeout_ms);","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Error code example","type":"text"}]},{"type":"codeBlock","content":[{"text":"// Bad: What is the significance of 3? What about other constants like 2 or 4?\nint error_code = TCP_connect(&connection, timeout_ms);\nif (3 == error_code) {\n // Do error handling logic\n}\n\n// Good: Intent is clear; the if condition handles a timeout error\nerror_code_e error_code = TCP_connect(&connection, timeout_ms);\nif (ERROR_CODE__TIMEOUT == error_code) {\n // Do error handling logic\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Size example","type":"text"}]},{"type":"codeBlock","content":[{"text":"/* \n * Bad: Avoid using an auxiliary variable to define an array size (it's not necessary in this example)\n * While 65535 may seem obvious to some, it's still unnecessarily obscure\n */ \n#define BUFFER_SIZE 65535;\nstatic uint8_t buffer[BUFFER_SIZE];\n// Bad: Copy buffer mirrors buffer implicitly; this is prone to human error\nstatic uint8_t copy_buffer[BUFFER_SIZE];\n\nvoid test_read_buffer(void) {\n // Bad: The size of the buffer should be derived from the buffer itself (one source of truth)\n read_buffer(buffer, BUFFER_SIZE);\n\n // Simulate buffer overflow\n // Bad: 65536 is an obscure way of expressing larger than the buffer size\n // If the buffer size changes in the future, a maintainer may forget to update this constant\n read_buffer(buffer, 65536);\n}\n\n/*\n * Good: Prefer to use constants derived from existing constants\n * 65535 truly represents the max representation of 16 bits\n */\nstatic uint8_t buffer[(1U << 16U) - 1U];\n// Good: Copy buffer mirrors buffer explicitly\nstatic uint8_t copy_buffer[sizeof(buffer)];\n\nvoid test_read_buffer(void) {\n // Good: Use `sizeof` on the array itself to get its size (one source of truth)\n read_buffer(buffer, sizeof(buffer));\n\n // Simulate buffer overflow\n /*\n * Good: Derived size clearly expresses 1 byte greater than actual size\n * Always derive numbers from some source of truth if buffer size changes in the future,\n * then there's no need to update this statement\n */\n read_buffer(buffer, sizeof(buffer) + 1);\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Again, magic numbers are defined as obscure constants, so don’t do the obvious. For example, this statement is obvious and unnecessary:","type":"text"}]},{"type":"codeBlock","content":[{"text":"const int zero = 0;","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Avoid vague names","type":"text"}]},{"type":"paragraph","content":[{"text":"Avoid these:","type":"text"}]},{"type":"codeBlock","content":[{"text":"// What operation?\nvoid my_module__perform_operation();\n\n// What type of info?\nvoid my_module__update_info();","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Use Relative Includes","type":"text"}]},{"type":"paragraph","content":[{"text":"Shown below are two ways to include a code module. We recommend going with Option 1 for the reasons mentioned below.","type":"text"}]},{"type":"codeBlock","content":[{"text":"// Option 1\n#include \"sl_data_carrier.h\"\n// Option 2\n#include \"../buffers/sl_data_carrier.h\"","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If files move around, we will not have to change code dependencies","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If there are conflicts to file includes (customer ","type":"text"},{"text":"common.h","type":"text","marks":[{"type":"code"}]},{"text":" vs. our ","type":"text"},{"text":"common.h","type":"text","marks":[{"type":"code"}]},{"text":") then we have plans to mitigate the problem","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Our code modules have layer names, and the chance of conflict are minimal .i.e: ","type":"text"},{"text":"sl_common.h","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"One time software integration offsets the cost of relative includes","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Module Design","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Some of the main things included in a great module design are: data hiding, full code testability and compile time configuration of the module (so there are less pointers and no dynamic memory allocations, etc).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"One producer, many consumers","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Only one module should be allowed to set (i.e. produce) a particular variable. For example, only the seats module should be allowed to set the value for the ","type":"text"},{"text":"seats_occupied","type":"text","marks":[{"type":"code"}]},{"text":" variable.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No public data","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If the variable is required for some other behavior outside of the seats module, then it should only be accessed via get functions.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use accessor functions to access data","type":"text","marks":[{"type":"strong"}]},{"text":" that is internal to a module. Using functions instead of global variables helps improve trace-ability of where a variable is used, prevents accidental writes by other modules, and helps create stub functions when we are writing unit tests.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No global variables in the header file","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"You do not want to expose your data to anyone without an explicit API","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"You cannot declare instances of variables in a header file because each file including it will have its own instance leading to linking error with multiple definitions of the same name","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not use ","type":"text"},{"text":"extern","type":"text","marks":[{"type":"code"}]},{"text":" in a header file","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No inline functions","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Inline functions cannot be mocked for unit testing. When mocking a typical function we replace a functions definition with our own definition (this is done by compiling with a mock.c file that replaces of the real one). However we keep the header file with the function declarations because the code we're testing relies on this. Because inline functions are both declared and defined in the header file we can't replace the already existing definition and therefore are unable to create mocks for inline functions that exist in header files.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Inline functions are not picked up by Doxygen","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Inline is just a recommendation for some compilers","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Too many invocations to the inline function will bloat code, and actually make it run slower (due to cache misses)","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Private struct for all working variables","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"All variables required by a module shall be in a private struct that is defined inside the C source file. This makes it easy to see at a glance all the working variables of a module.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"It makes the code easier to multi-thread in the future (because a pointer to the struct can be passed in to each of the functions)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The struct should be named like ","type":"text"},{"text":"__data_s","type":"text","marks":[{"type":"code"}]},{"text":" and the name of the variable should be ","type":"text"},{"text":"__data","type":"text","marks":[{"type":"code"}]},{"text":". It is important to specify the layer in the name, only because we have both ","type":"text"},{"text":"app_seats.c","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"io_seats.c","type":"text","marks":[{"type":"code"}]},{"text":" in the code base and the working variables for each should be differentiated.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In ","type":"text"},{"text":"app_seats.c","type":"text","marks":[{"type":"code"}]},{"text":", it would be called ","type":"text"},{"text":"app_seats_data_s","type":"text","marks":[{"type":"code"}]},{"text":" and the name of the variable would be ","type":"text"},{"text":"app_seats_data","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In ","type":"text"},{"text":"io_seats.c","type":"text","marks":[{"type":"code"}]},{"text":", it would be called ","type":"text"},{"text":"io_seats_data_s","type":"text","marks":[{"type":"code"}]},{"text":" and the name of the variable would be ","type":"text"},{"text":"io_seats_data","type":"text","marks":[{"type":"code"}]}]}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No access from lower layers to higher layers","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Horizontal or downward code access only.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Code in a particular layer can only call other code in that layer or in the layer that is immediately below it. So, for example, app_seats.c can call app_airbag.c because it is another app. It can also call dev_seats because dev is the layer immediately below app.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No static variables inside functions","type":"text","marks":[{"type":"strong"}]},{"text":" (Does not apply to static const)","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"They are hard to test since they do not ","type":"text"},{"text":"tear down","type":"text","marks":[{"type":"code"}]},{"text":" correctly","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"They create cross-thread race conditions as it is a single instance that may be accessed and manipulated across multiple tasks (or threads).","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Prefer to add any such memory within the main module ","type":"text"},{"text":"struct","type":"text","marks":[{"type":"code"}]},{"text":" instead","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If it is indeed a single ","type":"text"},{"text":"app","type":"text","marks":[{"type":"code"}]},{"text":" then declare it global in the source file rather than inside of a function","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example:","type":"text"}]}]}]}]}]},{"type":"codeBlock","content":[{"text":" void func1(void) {\n // NO STATIC VARIABLES INSIDE FUNCTIONS!\n static uint8_t local = 0;\n }","type":"text"}]},{"type":"rule"},{"type":"heading","attrs":{"level":1},"content":[{"text":"Data Structure Guidelines","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Strict types","type":"text"}]},{"type":"paragraph","content":[{"text":"When defining arrays, the use of hardcoded values and macros for array sizes must be avoided. Instead, the memory should be wrapped in a struct.","type":"text"}]},{"type":"paragraph","content":[{"text":"Do not:","type":"text"}]},{"type":"codeBlock","content":[{"text":"// Avoid\nuint8_t packet[32U];\n\n// Avoid\n#define ARRAY_SIZE (32U)\nuint8_t packet[ARRAY_SIZE]","type":"text"}]},{"type":"paragraph","content":[{"text":"Typedefs are generally preferred, but they can also lead to problems ","type":"text"},{"text":"in this example","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"2a418d32-ed8e-46e6-9a0f-6bf7eb470daa"}},{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"03c7e113-4fe7-45f4-b362-455311e2b48c"}}]},{"text":":","type":"text"}]},{"type":"codeBlock","content":[{"text":"// We could do this:\ntypedef uint8_t packet_t[32];\n\nvoid process_packet(packet_t packet) {\n}\n\nvoid main(void) {\n uint8_t data[2];\n process_packet(data); // UNSAFE code, but compiler does not complain\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Hence, the better approach is to wrap the packet type inside of a struct in order to make the types more strict:","type":"text"}]},{"type":"codeBlock","content":[{"text":"typedef struct {\n uint8_t data[32];\n} packet_s;\n\nvoid process_packet(packet_s *packet) {\n}\n\nvoid main(void) {\n packet_s packet;\n process_packet(&packet); // OK; type matches and ensures packet/array is strictly the right size\n}","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Containerize Associated Data","type":"text"}]},{"type":"paragraph","content":[{"text":"Consider a case in which there is a pointer to memory, and size of the memory. The disadvantage of separate variables are:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Variable names need to be accurate to describe the intent that ","type":"text"},{"text":"memory_size","type":"text","marks":[{"type":"code"}]},{"text":" is associated with the ","type":"text"},{"text":"memory","type":"text","marks":[{"type":"code"}]},{"text":" pointer","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Passing data from one function to another requires two parameters","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":"void process_data(void *memory, size_t memory_size);","type":"text"}]},{"type":"paragraph","content":[{"text":"Instead, opt to use a container:","type":"text"}]},{"type":"codeBlock","content":[{"text":"typedef struct {\n void *data;\n size_t data_size_in_bytes;\n} sl_data_s;\n\nprocess_data(sl_data_s data);","type":"text"}]},{"type":"paragraph","content":[{"text":"Using ","type":"text"},{"text":"sl_data_s","type":"text","marks":[{"type":"code"}]},{"text":" in this examples consolidates related data, and avoids loosely coupled variables. This kind of concept is more natural in C++ as it has containers such as ","type":"text"},{"text":"vector","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"list","type":"text","marks":[{"type":"code"}]},{"text":" that have its related variables inside a single container, but in C, we have to take this step ourselves. ","type":"text"},{"text":"ISO CPP Guidelines","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/isocpp/CppCoreGuidelines/blob/master/docs/gsl-intro.md#gslspan-what-is-gslspan-and-what-is-it-for"}}]},{"text":" uses ","type":"text"},{"text":"span","type":"text","marks":[{"type":"code"}]},{"text":" container that would contain the array and its size for example.","type":"text"}]},{"type":"rule"},{"type":"heading","attrs":{"level":1},"content":[{"text":"Software Layering","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Whitespace & Code Format","type":"text"}]},{"type":"paragraph","content":[{"text":"Newer languages like Golang have whitespace rules, such as the brace positions built into the language. We chose to implement same idea by using ","type":"text"},{"text":"clang-format","type":"text","marks":[{"type":"code"}]},{"text":", which auto formats the source code according to pre-set rules such that ","type":"text"},{"text":"we focus our code reviews on the actual matter, and not the code format","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Sibros has ","type":"text"},{"text":"clang-format","type":"text","marks":[{"type":"code"}]},{"text":" set up to auto-format your code during ","type":"text"},{"text":"git commit","type":"text","marks":[{"type":"code"}]},{"text":". Google C++ code ","type":"text"},{"text":"whitespace","type":"text","marks":[{"type":"strong"}]},{"text":" formatting rules are used to format code during a ","type":"text"},{"text":"post-commit","type":"text","marks":[{"type":"code"}]},{"text":" hook. The only exception to the Google rules is that we use ","type":"text"},{"text":"120","type":"text","marks":[{"type":"strong"}]},{"text":" character limit for lines instead of 80 characters.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Layers","type":"text"}]},{"type":"paragraph","content":[{"text":"There are two primary objectives for layering the code:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"You should be able to look at any piece of code and assess what it does, where it lives and which other layers and functions it interacts with.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Each code module should be in a namespace of its own layer that indicates its intent and describes where it fits in the hierarchy.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Shown below are two high level diagrams of the system/software architecture, as well as an explanation for each layer.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"System Architecture","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":1003,"id":"cad42971-7d92-4b3d-b3b2-295d5875c5c0","collection":"contentId-101777636","type":"file","height":503}}]},{"type":"paragraph","content":[{"text":"Software Architecture","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":562,"id":"b2ef9a44-c912-48ca-bc98-d78978a0e016","collection":"contentId-101777636","type":"file","height":482}}]},{"type":"paragraph","content":[{"text":"The layers are:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"app_ ","type":"text","marks":[{"type":"code"}]},{"text":": ","type":"text"},{"text":"Application Layer","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Application layer is the highest level SW layer, where the high level system behaviors and features are implemented.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"dev_ ","type":"text","marks":[{"type":"code"}]},{"text":": ","type":"text"},{"text":"Device Communication Layer","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The device layer provides access to physical devices that may be connected and controlled by an ECU. The API for modules in this layer provides the access and control of these devices, abstracting away the ECU HW that is used to physically control and communicate with them. Therefore, the module using the API can be abstracted from the ECU and become portable to any ECU that has implemented the device layer module. This layer is also abstracting away the physical location of the device being controlled, such that the device could actually be connected via a communication bus and commanded remotely. Therefore, this layer acts as a communication abstraction layer to other devices and ECUs.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"ecu_ ","type":"text","marks":[{"type":"code"}]},{"text":": ","type":"text"},{"text":"ECU and Complex IO Layer","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Provides access to interface with ECU board level HW. These interfaces abstract away the HW details, such as which particular circuits or ICs are on the board, and instead provide a common interface layer to control the functions these circuits provide. This allows higher level control of ECU pins, abstracting away the details of the circuits driving those pins. This allows for a common interface to control an ECU, regardless of which variant of ECU hardware is actually being operated on.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"mcu_ ","type":"text","marks":[{"type":"code"}]},{"text":": ","type":"text"},{"text":"Microcontroller and Low Level IO Layer","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Used to interface with microcontrollers, allowing control of the micro’s pins, and operating states, without having to directly access the micro’s peripherals or CPU cores. Modules at this layer implement basic drivers that utilize a particular microcontroller’s peripherals and CPU core. This layer abstracts away the microcontroller, allowing for a common interface layer across different microcontrollers.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"perif_","type":"text","marks":[{"type":"code"}]},{"text":": ","type":"text"},{"text":"Microcontroller Peripheral and CPU Core Layer","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Used to interface with peripherals and CPU cores. This gives the ability to control and access a peripheral, without having to directly access registers or peripheral memory. The interfaces for a given module provide abstraction to the specifics of the peripheral, allowing for the same interfaces to be used across multiple variations of the peripheral. Variations might include the number of channels or number of instances of that peripheral. A peripheral may be used in various microcontroller families, so having an interface layer to the peripheral allows for reuse across microcontrollers.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"os_ ","type":"text","marks":[{"type":"code"}]},{"text":": ","type":"text"},{"text":"OS Abstraction Layer (including RTOS)","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The OS layer provides a common abstraction layer from the underlying operating system (OS). This allows the code to be portable to any ECU, regardless of the underlying OS, even a bare-metal system.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"sl_ ","type":"text","marks":[{"type":"code"}]},{"text":": ","type":"text"},{"text":"Standalone and Utility Library Layer","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Code modules in this layer are implemented as pure functions or utility macros, or define standard types. These modules have no internal state, do not have external dependencies, and do not have run tasks. They are mathematical libraries, conversion functions, or standardized type definitions. The only external dependencies allowed would be other standard utility library modules.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example 1:","type":"text","marks":[{"type":"em"}]},{"text":" ","type":"text"},{"text":"sl_crc32","type":"text","marks":[{"type":"code"}]},{"text":" only operates on data passed as parameters to it's API. It operates on the parameters and returns a result. It does internally store any data, and therefore contains no internal state or memory.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example 2:","type":"text","marks":[{"type":"em"}]},{"text":" ","type":"text"},{"text":"sl_uds_server","type":"text","marks":[{"type":"code"}]},{"text":" is a complex module that depends on other ","type":"text"},{"text":"SL","type":"text","marks":[{"type":"code"}]},{"text":" modules, but still does not store any data internally. All information is passed via parameters to the API. Any static information is stored within the application that creates an instance of ","type":"text"},{"text":"sl_uds_server","type":"text","marks":[{"type":"code"}]},{"text":", and simply uses the ","type":"text"},{"text":"sl_uds_server","type":"text","marks":[{"type":"code"}]},{"text":" API to opperate on that instance.","type":"text"}]}]}]}]}]}]}]},{"type":"paragraph"},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":33.33},"content":[{"type":"paragraph"},{"type":"paragraph"},{"type":"paragraph"},{"type":"paragraph"},{"type":"table","attrs":{"layout":"default","localId":"ca76269e-ba34-406c-948a-f2273356c742"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[191.0]},"content":[{"type":"paragraph","content":[{"text":"Cannot Access","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#fff0b3","rowspan":1,"colwidth":[198.0]},"content":[{"type":"paragraph","content":[{"text":"Advise Against Access","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[190.0]},"content":[{"type":"paragraph","content":[{"text":"Can Access","type":"text"}]}]}]}]}]},{"type":"layoutColumn","attrs":{"width":66.66},"content":[{"type":"table","attrs":{"layout":"default","localId":"4763f5e3-343c-4528-bdfc-3b3d6026bdca"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":2,"colwidth":[318.0]},"content":[{"type":"paragraph"},{"type":"paragraph","marks":[{"type":"alignment","attrs":{"align":"center"}}],"content":[{"text":"Layer that is accessed","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":7,"rowspan":1,"colwidth":[118.0,124.0,124.0,124.0,121.0,125.0,129.0]},"content":[{"type":"paragraph","marks":[{"type":"alignment","attrs":{"align":"center"}}],"content":[{"text":"Layer in question","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[118.0]},"content":[{"type":"paragraph","content":[{"text":"app","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph","content":[{"text":"dev","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph","content":[{"text":"ecu","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph","content":[{"text":"mcu","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[121.0]},"content":[{"type":"paragraph","content":[{"text":"perif","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[125.0]},"content":[{"type":"paragraph","content":[{"text":"os","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[129.0]},"content":[{"type":"paragraph","content":[{"text":"sl","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[318.0]},"content":[{"type":"paragraph","marks":[{"type":"alignment","attrs":{"align":"end"}}],"content":[{"text":"app","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[118.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[121.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[125.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[129.0]},"content":[{"type":"paragraph"}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[318.0]},"content":[{"type":"paragraph","marks":[{"type":"alignment","attrs":{"align":"end"}}],"content":[{"text":"dev","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[118.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[121.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[125.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[129.0]},"content":[{"type":"paragraph"}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[318.0]},"content":[{"type":"paragraph","marks":[{"type":"alignment","attrs":{"align":"end"}}],"content":[{"text":"ecu","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#fff0b3","rowspan":1,"colwidth":[118.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[121.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[125.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[129.0]},"content":[{"type":"paragraph"}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[318.0]},"content":[{"type":"paragraph","marks":[{"type":"alignment","attrs":{"align":"end"}}],"content":[{"text":"mcu","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#fff0b3","rowspan":1,"colwidth":[118.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#fff0b3","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[121.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[125.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[129.0]},"content":[{"type":"paragraph"}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[318.0]},"content":[{"type":"paragraph","marks":[{"type":"alignment","attrs":{"align":"end"}}],"content":[{"text":"perif","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[118.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[121.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[125.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[129.0]},"content":[{"type":"paragraph"}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[318.0]},"content":[{"type":"paragraph","marks":[{"type":"alignment","attrs":{"align":"end"}}],"content":[{"text":"os","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[118.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[121.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[125.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#ffbdad","rowspan":1,"colwidth":[129.0]},"content":[{"type":"paragraph"}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[318.0]},"content":[{"type":"paragraph","marks":[{"type":"alignment","attrs":{"align":"end"}}],"content":[{"text":"sl","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[118.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[124.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[121.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[125.0]},"content":[{"type":"paragraph"}]},{"type":"tableCell","attrs":{"colspan":1,"background":"#abf5d1","rowspan":1,"colwidth":[129.0]},"content":[{"type":"paragraph"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Double Underscore","type":"text"}]},{"type":"paragraph","content":[{"text":"Double underscores are used to quickly distinguish what layer and module something belongs to. All functions, variables, structs, enums and unions in a file should match the file name. Please look at the diagram below and the explanations that follow afterwards.","type":"text"}]},{"type":"codeBlock","content":[{"text":"c_code/\n+ dev/\n| + dev_file_io/\n| + dev_file_io.h\n| | + public header with API for dev_file_io\n| | + declares all dev_file_io__* functions\n| + littlefs/\n| | + dev_file_io.c\n| | | + includes dev_file_io.h\n| | | + all dev_file_io__* functions defined\n| | | + includes dev_file_io_littlefs.h\n| | | + includes dev_file_io_private.h\n| | | + can make calls to dev_file_io_littlefs__* functions\n| | + dev_file_io_private.h\n| | | + contains private information for dev_file_io.c\n| | + dev_file_io_littlefs.h\n| | | + declares all littlefs specific functions that dev_file_io.c would need to call\n| | + dev_file_io_littlefs.c\n| | | + includes dev_file_io_littlefs.h\n| | | + defines all littlefs specific functions\n| | | + makes all the actual calls to lfs_*\n| + lpc40xx/\n| | + Similar layout as littlefs folder\n| + posix/\n| | + Similar layout as littlefs folder\n","type":"text"}]},{"type":"paragraph","content":[{"text":"Observe the following:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Each variant contains ","type":"text"},{"text":"dev_file_io.c","type":"text","marks":[{"type":"code"}]},{"text":" in their folder. This implements all the public functions defined in the main header file ","type":"text"},{"text":"dev_file_io.h","type":"text","marks":[{"type":"code"}]},{"text":". Additionally, if extra public functions need to be defined for this particular variant, they would live in a new file called ","type":"text"},{"text":"dev_file_io_posix.c/.h","type":"text","marks":[{"type":"code"}]},{"text":" and all code in those files would start with the name ","type":"text"},{"text":"dev_file_io_posix__","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"When integrating ","type":"text"},{"text":"dev_file_io","type":"text","marks":[{"type":"code"}]},{"text":" into a project, the integrator will configure which variant to use. So, if the project is a POSIX based system, then they would integrate the ","type":"text"},{"text":"posix","type":"text","marks":[{"type":"code"}]},{"text":" variant.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Include Guard","type":"text"}]},{"type":"paragraph","content":[{"text":"Sibros initially went with ","type":"text"},{"text":"#pragma once","type":"text","marks":[{"type":"code"}]},{"text":" as an include guard. The thought process was that \"most\" compilers support this compiler pre-processor tag. Sibros, however, supports multitude of OEMs and a diverse set of compilers and we eventually ran into a ","type":"text"},{"text":"Tasking","type":"text","marks":[{"type":"code"}]},{"text":" compiler that would not recognize the ","type":"text"},{"text":"pragma once","type":"text","marks":[{"type":"code"}]},{"text":" and had to revise the strategy. Therefore, the include guard standard is:","type":"text"}]},{"type":"codeBlock","content":[{"text":"#ifndef SIBROS___H\n#define SIBROS___H\n\n// ... code\n\n#endif /* #ifndef SIBROS___H */","type":"text"}]},{"type":"paragraph","content":[{"text":"The reason to tag with ","type":"text"},{"text":"SIBROS__","type":"text","marks":[{"type":"code"}]},{"text":" is that it guarantees that we will not run into third party code base that happens to use the same name for the include guard, and therefore have to make the include guard unique.","type":"text"}]},{"type":"paragraph","content":[{"text":"For ","type":"text"},{"text":"C++","type":"text","marks":[{"type":"strong"}]},{"text":" code base, follow the ","type":"text"},{"text":"#pragma once","type":"text","marks":[{"type":"code"}]},{"text":" for header files. For C++ code base we deviated from the C include guard because C++ codebase is dominantly compiled in GCC or similar modern compilers and C++ code base is usually not compiled by diverse set of embedded/C compilers. We decided to use this after weighing in on the benefits and the side-effects. The Wikipedia definition is on the harsh side against its use, but there are benefits to avoiding the cryptic ","type":"text"},{"text":"#ifndef FOLDER_FOO_HEADER_H__","type":"text","marks":[{"type":"code"}]},{"text":" style.","type":"text"}]},{"type":"paragraph","content":[{"text":"Reasons in favor:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoids boiler-plate code","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoids creating a unique ","type":"text"},{"text":"#ifdef","type":"text","marks":[{"type":"code"}]},{"text":" guard","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Reasons against:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A small fraction of the compilers do not support this","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":"#pragma once\n\nvoid foo(void);","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"C++ ","type":"text"},{"text":"extern","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"The following block of code is required so that C++ code can use C header files and call the C code. Please note that this is only required in header files and not required in source files.","type":"text"}]},{"type":"codeBlock","content":[{"text":"#ifndef SIBROS___H\n#define SIBROS___H\n\n#ifdef __cplusplus\nextern \"C\" {\n#endif\n\nvoid foo(void);\n\n#ifdef __cplusplus\n} /* extern \"C\" */\n#endif\n\n#endif /* #ifndef SIBROS___H */","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Order of Includes","type":"text"}]},{"type":"paragraph","content":[{"text":"Follow the examples below, but note that the comments in between include blocks should be used to separate different groups of includes otherwise ","type":"text"},{"text":"clang-format","type":"text","marks":[{"type":"code"}]},{"text":" will re-order the includes in alphabetical order. The order of include is important because during unit-tests, we hijack the meaning of ","type":"text"},{"text":"static","type":"text","marks":[{"type":"code"}]},{"text":" keyword and unfortunately the order of includes can lead to trouble during unit-tests. The ","type":"text"},{"text":"Unit-Test article","type":"text","marks":[{"type":"link","attrs":{"href":"https://gitlab.com/sibros_public/public/-/wikis/c/Unit-Testing-for-C"}}]},{"text":" further discusses why we hijacked ","type":"text"},{"text":"static","type":"text","marks":[{"type":"code"}]},{"text":" instead of inventing a new keyword, such as ","type":"text"},{"text":"STATIC","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Standard Includes consist of standard C libs, and should be included with < > instead of \" \"","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"External Includes consist of any module that is not the one we are writing, regardless of whether it is in-house or third-party","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Module Includes consist of all files that are specific to the module we are writing","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Header File","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A module's header file should not include ","type":"text"},{"text":"sl_unit_test_facilitator.h","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"codeBlock","content":[{"text":"/* Standard Includes */\n\n/* External Includes */\n\n/* Module Includes */\n","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Private Header File","type":"text"}]},{"type":"paragraph","content":[{"text":"Not all code modules have to have the private header file. Private function declarations for a code module should go in the ","type":"text"},{"text":"*_private.h","type":"text","marks":[{"type":"code"}]},{"text":" file. This is because the unit tests may need to access the ","type":"text"},{"text":"static","type":"text","marks":[{"type":"code"}]},{"text":" functions to perform detailed tests.","type":"text"}]},{"type":"paragraph","content":[{"text":"The order of includes is just like an ordinary header file, except that we include ","type":"text"},{"text":"sl_unit_test_facilitator.h","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"last","type":"text","marks":[{"type":"strong"}]},{"text":" to hijack the ","type":"text"},{"text":"static","type":"text","marks":[{"type":"code"}]},{"text":" keyword such that it has no effect during unit-tests. After this file is included, and only during the Unit-Tests, it replaces the meaning of ","type":"text"},{"text":"static","type":"text","marks":[{"type":"code"}]},{"text":" with ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" such that the code's private functions are not private and this facilitates Unit-Testing.","type":"text"}]},{"type":"codeBlock","content":[{"text":"/* Standard Includes */\n\n/* External Includes */\n\n/* Module Includes */\n\n#include \"sl_unit_test_facilitator.h\"\n","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Source File","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The source file's header, additionally handles the logic of determining if the module's feature flag is defined. Consequently, the header is included first so that we can inherit the module's feature flag as early as possible in the source file","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The source file's private header should be included last","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The desire is to re-define ","type":"text"},{"text":"static","type":"text","marks":[{"type":"code"}]},{"text":" as late as possible","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If you have the ","type":"text"},{"text":"*_private.h","type":"text","marks":[{"type":"code"}]},{"text":" version of your header file, then that includes ","type":"text"},{"text":"sl_unit_test_facilitator.h","type":"text","marks":[{"type":"code"}]},{"text":" already, so no inclusion is necessary explicitly.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If you do not have ","type":"text"},{"text":"*_private.h","type":"text","marks":[{"type":"code"}]},{"text":" then:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Include ","type":"text"},{"text":"sl_unit_test_facilitator.h","type":"text","marks":[{"type":"code"}]},{"text":" in place of ","type":"text"},{"text":"*_private.h","type":"text","marks":[{"type":"code"}]}]}]}]}]}]},{"type":"codeBlock","content":[{"text":"/* Main Module Header */\n\n// #include \"{__name__}.h\"\n\n/* Standard Includes */\n\n/* External Includes */\n\n/* Private Module Includes */\n\n// #include \"{__name__}_private.h\" // either this\n// #include \"sl_unit_test_facilitator.h\" // or this\n","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Unit Test file","type":"text"}]},{"type":"codeBlock","content":[{"text":"/* Standard Includes */\n#include \"unity.h\"\n\n/* Mock Includes */\n\n/* External Includes */\n\n/* Module Includes */\n\n// #include \"{__name__}.h\"\n// #include \"{__name__}_private.h\" // either this\n// #include \"sl_unit_test_facilitator.h\" // or this\n","type":"text"}]},{"type":"rule"},{"type":"heading","attrs":{"level":1},"content":[{"text":"Naming Convention","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"General Rules","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Snake Case","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"After some research, we decided to go with ","type":"text"},{"text":"snake_case","type":"text","marks":[{"type":"code"}]},{"text":" or the ","type":"text"},{"text":"underscore","type":"text","marks":[{"type":"code"}]},{"text":" convention, primarily due to the following reasons:","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Snake case does not suffer from:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Differentiating Abbreviations ","type":"text"},{"text":"tcpIpOpen","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"I hate Camel Case","type":"text","marks":[{"type":"link","attrs":{"href":"https://yosefk.com/blog/ihatecamelcase.html"}}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Naming convention inside code can match the file names","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"myCodeModule.c","type":"text","marks":[{"type":"code"}]},{"text":" creates issues with diverse build systems (Windows vs. Linux)","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Therefore, use ","type":"text"},{"text":"snake_case","type":"text","marks":[{"type":"code"}]},{"text":" with no capital letters for all code, file and folder names","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not use ","type":"text"},{"text":"camelCase","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not use ","type":"text"},{"text":"PascalCase","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not use Hungarian notation (like ","type":"text"},{"text":"pMyString","type":"text","marks":[{"type":"code"}]},{"text":" for pointers, 'bSwitch' for booleans)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not mix dashes with underscores. e.g. ","type":"text"},{"text":"pre_integration_plan","type":"text","marks":[{"type":"code"}]},{"text":" is OK; ","type":"text"},{"text":"pre-integration_plan","type":"text","marks":[{"type":"code"}]},{"text":" is not OK.","type":"text"}]}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Names of basic types and code modules","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"UPPER_CASE_SNAKE_CASE","type":"text","marks":[{"type":"code"}]},{"text":" for","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Global and static global ","type":"text","marks":[{"type":"strike"}]},{"text":"Constants","type":"text","marks":[{"type":"strike"},{"type":"strong"}]},{"text":" (local variables that are const can be lowercase to differentiate between a global const variable vs. local const variable)","type":"text","marks":[{"type":"strike"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Upon further discussion, it was decided to use ","type":"text"},{"text":"lower_case_snake_case","type":"text","marks":[{"type":"code"}]},{"text":" for all variables, including constants. This is because we don’t want global const struct instances to be ","type":"text"},{"text":"UPPER_CASE_SNAKE_CASE","type":"text","marks":[{"type":"code"}]},{"text":", and we don’t want to make a confusing exception between global const scalar types being ","type":"text"},{"text":"UPPER_CASE_SNAKE_CASE","type":"text","marks":[{"type":"code"}]},{"text":" and global const aggregate types being ","type":"text"},{"text":"lower_case_snake_case","type":"text","marks":[{"type":"code"}]},{"text":". The original benefit of using ","type":"text"},{"text":"UPPER_CASE_SNAKE_CASE","type":"text","marks":[{"type":"code"}]},{"text":" for constants was to easily identify which variables are constant. However, all of our global constants are file scope, so const variables can easily be identified as being constant by viewing their declaration in the same file.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Macros","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Enumeration values","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Code Module","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Precede with layer name","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Create a header file, source file, and its corresponding unit-test file","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If there are private enums, typedefs, or functions, then also create the private module","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: ","type":"text"},{"text":"app_my_module.h","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"app_my_module.c","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"app_my_module_private.h","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"test_app_my_module.c","type":"text","marks":[{"type":"code"}]}]}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"All code, file names and folder names in lowercase","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"All acronyms shall be lowercase, just like all other names, whether they are part of functions, variables, or any other types","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The reason for this is to keep naming consistent with the file naming convention, which uses all lowercase","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: your module for Unified Diagnostic Services shall be abbreviated as ","type":"text"},{"text":"uds","type":"text","marks":[{"type":"code"}]},{"text":" and not ","type":"text"},{"text":"UDS","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use American English spelling","type":"text","marks":[{"type":"strong"}]},{"text":" and not British English spelling.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: ","type":"text"},{"text":"behavior","type":"text","marks":[{"type":"code"}]},{"text":" instead of ","type":"text"},{"text":"behaviour","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Because Sibros started in America","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No single letter variables, not even in ","type":"text","marks":[{"type":"strong"}]},{"text":"for","type":"text","marks":[{"type":"code"}]},{"text":" loops.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Instead of ","type":"text"},{"text":"i","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"j","type":"text","marks":[{"type":"code"}]},{"text":", use ","type":"text"},{"text":"index","type":"text","marks":[{"type":"code"}]},{"text":" or something else that describes what you are looping over","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Because you should have more meaning to the variable","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No Hungarian notation for variable names","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Because variables change meaning, or the notation doesn't convey any useful information. For example, do not create boolean variables starting with ","type":"text"},{"text":"b","type":"text","marks":[{"type":"code"}]},{"text":" like ","type":"text"},{"text":"b_door_open","type":"text","marks":[{"type":"code"}]},{"text":" and pointers with ","type":"text"},{"text":"p","type":"text","marks":[{"type":"code"}]},{"text":" like ","type":"text"},{"text":"p_battery_data","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Because this notation existed in the old days with lack of good IDEs","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No global variables that can be accessed using an ","type":"text","marks":[{"type":"strong"}]},{"text":"extern","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"You should make them ","type":"text"},{"text":"static","type":"text","marks":[{"type":"code"}]},{"text":" in your source code, to forbid ","type":"text"},{"text":"extern","type":"text","marks":[{"type":"code"}]},{"text":" access","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If you want to have access to a variable, it should be returned from a public access function","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Because we don’t want ","type":"text"},{"text":"peek and poke","type":"text","marks":[{"type":"code"}]},{"text":" code","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use the verb-noun method for naming","type":"text","marks":[{"type":"strong"}]},{"text":" routines that perform some operation on a given object, such as:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"app_battery__calculate_soc()","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This allows for the reader of the code to be able to easily understand the action that the function is taking.","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Variable Names","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use standard capitalization rules for measurement variables even if it breaks acronym and abbreviation naming rules. This is done to reduce confusion of someone reading the code and expecting certain standard capitalization for measurement variables (i.e. meter = m, watt = W, pascal = Pa).","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"speed_mph","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"time_left_ms","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Variables should be singular, and arrays should be plural.","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example:","type":"text"}]}]}]}]}]},{"type":"codeBlock","content":[{"text":" int book = 5;\n int books[3] = {4, 2, 5}; // an array of books","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Limit Abbreviations","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Examples:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"packet","type":"text","marks":[{"type":"code"}]},{"text":" instead of ","type":"text"},{"text":"pkt","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"calculate","type":"text","marks":[{"type":"code"}]},{"text":" instead of ","type":"text"},{"text":"calc","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"index","type":"text","marks":[{"type":"code"}]},{"text":" instead of ","type":"text"},{"text":"idx","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If abbreviations are used, be consistent in their use. An abbreviation should have only one meaning and likewise, each abbreviated word should have only one abbreviation.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"It is okay to use abbreviations for standard unit types (","type":"text"},{"text":"kg","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"ms","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"lbs","type":"text","marks":[{"type":"code"}]},{"text":")","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Here are some specific variables name that are not allowed:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not abbreviate ","type":"text"},{"text":"minimum","type":"text","marks":[{"type":"code"}]},{"text":" as ","type":"text"},{"text":"min","type":"text","marks":[{"type":"code"}]},{"text":" because what if someone later abbreviates ","type":"text"},{"text":"minute","type":"text","marks":[{"type":"code"}]},{"text":" as ","type":"text"},{"text":"min","type":"text","marks":[{"type":"code"}]},{"text":"?","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"No variables named ","type":"text"},{"text":"temp","type":"text","marks":[{"type":"code"}]},{"text":" because ","type":"text"},{"text":"temp","type":"text","marks":[{"type":"code"}]},{"text":" can mean ","type":"text"},{"text":"temporary","type":"text","marks":[{"type":"code"}]},{"text":", and can mean ","type":"text"},{"text":"temperature","type":"text","marks":[{"type":"code"}]},{"text":" also.","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"No Redundant Names","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In object-oriented languages, it is redundant to include class names in the name of class properties, such as ","type":"text"},{"text":"book.book_title","type":"text","marks":[{"type":"code"}]},{"text":". Instead, use ","type":"text"},{"text":"book.title","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This applies to things like structs, unions and enums.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoid repeating words like ","type":"text"},{"text":"queue","type":"text","marks":[{"type":"code"}]},{"text":": ","type":"text"},{"text":"void sl_queue__init_queue(...);","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"paragraph","content":[{"text":"Avoid the following because it has the object name repeated too many times:","type":"text"}]},{"type":"codeBlock","content":[{"text":"sl_data_carrier_s data_carrier_tcp;\nsl_data_carrier__append(&data_carrier_tcp);\n\n// Whenever 'data_carrier_tcp' is used, we will always use it\n// with this API name sl_data_carrier__() therefore adding\n// another 'data_carrier_' is redundant","type":"text"}]},{"type":"paragraph","content":[{"text":"Avoid repeating the module name in member variables of a struct.","type":"text"}]},{"type":"codeBlock","content":[{"text":"typedef struct {\n void *buffer_memory;\n size_t buffer_memory_size_bytes;\n} buffer_s;","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Types","type":"text"}]},{"type":"paragraph","content":[{"text":"We should be able to decipher the type looking at the name of the type. Therefore, follow the following naming convention for new types.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Enums: ","type":"text"},{"text":"typedef enum enum_e;","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Structs: ","type":"text"},{"text":"typedef struct struct_s;","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Unions: ","type":"text"},{"text":"typedef union union_u;","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Type: ","type":"text"},{"text":"typedef old_type new_type_t;","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Function Pointer: ","type":"text"},{"text":"typedef void (*func_ptr_f)(void);","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"paragraph","content":[{"text":"Avoid obscuring a type, for example: ","type":"text"},{"text":"typedef char hostname[32];","type":"text","marks":[{"type":"code"}]},{"text":". This makes the code unsafe because an aribtrary char array can get past the compiler checks:","type":"text"}]},{"type":"codeBlock","content":[{"text":"void set_default_hostname(hostname name) {\n strncpy(name, \"sibros\", sizeof(name) - 1);\n}\n\nvoid oops(void) {\n char hostname[2];\n set_default_hostname(hostname);\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"You can make this code safer by using a data structure which will avoid the ","type":"text"},{"text":"oops()","type":"text","marks":[{"type":"code"}]},{"text":" function above.","type":"text"}]},{"type":"codeBlock","content":[{"text":"typedef struct {\n char string[32];\n} hostname_s;","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Use strong types","type":"text"}]},{"type":"paragraph","content":[{"text":"Avoid creating types that can fail basic sanity checks. Here is an example:","type":"text"}]},{"type":"codeBlock","content":[{"text":"typedef char array_type[32];\nvoid set_data(array_type array) {\n // ...\n}\n\nvoid main(void) {\n char data[2];\n set_data(data); // Oops\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Instead, opt for better types:","type":"text"}]},{"type":"codeBlock","content":[{"text":"typedef struct {\n char data[32];\n} data_t;\n\nvoid set_data(data_t *data_ptr);","type":"text"}]},{"type":"paragraph","content":[{"text":"Also, avoid macros that can make it through type checks. C may be limited (no C++ templates), but you rather be safe than sorry.","type":"text"}]},{"type":"codeBlock","content":[{"text":"// DO NOT DO THIS\n#define MIN_OF(X, Y)\n\n// In C, define mins explicitly, and of course, do not use a macro\nuint8_t min_of_uint8(uint8_t x, uint8_t y);\nuint16_t min_of_uint16(uint16_t x, uint16_t y);\nuint32_t min_of_uint32(uint32_t x, uint32_t y);","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Preferred Types","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Use ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoid using ","type":"text"},{"text":"int","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"long","type":"text","marks":[{"type":"code"}]},{"text":" because they may not port across CPUs with different bit-width","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Instead use explicit ","type":"text"},{"text":"uint32_t","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"int64_t","type":"text","marks":[{"type":"code"}]},{"text":" etc.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not define your own bool (examples: BOOL, _bool, bool_t), use ","type":"text"},{"text":"#include ","type":"text","marks":[{"type":"code"}]},{"text":" instead","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Use ","type":"text"},{"text":"size_t","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"size_t","type":"text","marks":[{"type":"code"}]},{"text":" for any \"size types\" of unsigned numbers","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use for indexes, and container sizes, much like the C++ library","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Do not use ","type":"text"},{"text":"size_t","type":"text","marks":[{"type":"code"}]},{"text":" when you want the size to be explicit","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: ","type":"text"},{"text":"uint32_t","type":"text","marks":[{"type":"code"}]},{"text":" for a 32-bit address of SPI flash","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"ssize_t","type":"text","marks":[{"type":"code"}]},{"text":" for any signed types","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Functions","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Public functions","type":"text","marks":[{"type":"strong"}]},{"text":" should be separated from the layer and the module name with two underscores.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Pattern: ","type":"text"},{"text":"___();","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"_","type":"text","marks":[{"type":"code"}]},{"text":" in the function name must match the file name","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Examples:","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"app_traction_control__init()","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"app_lights__disable()","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"app_battery__calculate_soc()","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Private functions","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Shall have layer and module in the name.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Shall have the word ","type":"text"},{"text":"private","type":"text","marks":[{"type":"code"}]},{"text":" in it","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This improves code readability because in a large code module, it is easier to differentiate the function invocation internal or external to the code module","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Pattern: ","type":"text"},{"text":"___private_();","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"_","type":"text","marks":[{"type":"code"}]},{"text":" in the function name must match the file name","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Examples:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"void sl_uds_client__private_func(void);","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"app_battery__private_update_soc(void)","type":"text","marks":[{"type":"code"}]}]}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Test functions","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Pattern: ","type":"text"},{"text":"test______();","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"_","type":"text","marks":[{"type":"code"}]},{"text":" in the function name must match the file name","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Examples:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"test_app_traction_control__init__initalization_fails()","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"test_app_lights__disable__parameter_is_null()","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"test_app_battery__calculate_soc__invalid_soc()","type":"text","marks":[{"type":"code"}]}]}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Callback Functions","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Callback functions should always contain an argument as this allows the caller to provide context to the function. This allows a single callback function to be used for multiple cases.If the argument is of void* then ensure that the argument is not a const.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Incorrect Method:","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":"typedef void (callback*)(void);\n\n// And for an API:\nvoid register_callback(int slot, callback);\n\nvoid callback1(void) {\n}\n\nvoid callback2(void) {\n}\n\n// Multiple callbacks required\nregister_callback(0, callback1);\nregister_callback(1, callback2);\n","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Correct Method:","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":"// We desire to have an argument parameter and not a void:\ntypedef void (callback*)(void * arg_during_callback);\n\n// And for an API:\nvoid register_callback(int slot, callback, void *arg_during_callback);\n\nvoid callback(void * arg) {\n if (0xDEAD == arg) {\n } else {\n }\n} \n\n// Reason is that we can re-use a single callback:\nregister_callback(0, callback, 0xDEAD);\nregister_callback(1, callback, 0xBEEF);","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Enums","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Typedef Name Pattern: ","type":"text"},{"text":"____e","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"_","type":"text","marks":[{"type":"code"}]},{"text":" in the enum name must match the file name, unless the file is in format ","type":"text"},{"text":"__types","type":"text","marks":[{"type":"code"}]},{"text":", eg. (","type":"text"},{"text":"mcu_can_types.h","type":"text","marks":[{"type":"code"}]},{"text":" has ","type":"text"},{"text":"mcu_can__hw_mailbox_e","type":"text","marks":[{"type":"code"}]},{"text":")","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: ","type":"text"},{"text":"app_battery__status_codes_e;","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Tag Name Pattern: ","type":"text"},{"text":"____tag","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"_","type":"text","marks":[{"type":"code"}]},{"text":" in the enum name must match the file name, unless the file is in format ","type":"text"},{"text":"__types","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: ","type":"text"},{"text":"app_battery__status_codes_tag","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Tag is optional, but must follow this convention if included","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Start the first enum value at zero","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Prefer to use an ","type":"text"},{"text":"unspecified","type":"text","marks":[{"type":"code"}]},{"text":" value for the first enum","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"(Optional) Define a ","type":"text"},{"text":"count","type":"text","marks":[{"type":"code"}]},{"text":" value only for iterable lists","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This can be used for sizing arrays of structs, where each element is identified by an enum.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Put a comma at the last enum value","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Creates less ","type":"text"},{"text":"diff","type":"text","marks":[{"type":"em"}]},{"text":" during code review","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Allows you to move enums without a compiler error","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Values inside the enum table should use the specific name of the enum","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: ","type":"text"},{"text":"___","type":"text","marks":[{"type":"code"}]}]}]}]}]}]},{"type":"paragraph","content":[{"text":"Example","type":"text"}]},{"type":"codeBlock","content":[{"text":"typedef enum {\n APP_BATTERY__STATUS_CODE_UNSPECIFIED = 0,\n APP_BATTERY__STATUS_CODE_CHARGING,\n APP_BATTERY__STATUS_CODE_DISCHARGING,\n APP_BATTERY__STATUS_CODE_IDLE,\n} app_battery__status_code_e; ","type":"text"}]},{"type":"paragraph","content":[{"text":"Example of a list","type":"text"}]},{"type":"codeBlock","content":[{"text":"typedef enum {\n MCU_PORTPIN__PIN_CAN0_RX,\n MCU_PORTPIN__PIN_CAN0_TX,\n MCU_PORTPIN__PIN_CAN_ID0,\n MCU_PORTPIN__PIN_CAN_STB,\n MCU_PORTPIN__PIN_WATCHDOG,\n MCU_PORTPIN__PIN_COUNT, \n} mcu_portpin__pin_e;","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Structs","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Typedef Name Pattern: ","type":"text"},{"text":"____s","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"__s","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"_","type":"text","marks":[{"type":"code"}]},{"text":" in the struct name must match the file name, unless the file is in format ","type":"text"},{"text":"__types","type":"text","marks":[{"type":"code"}]},{"text":", eg. (","type":"text"},{"text":"mcu_can_types.h","type":"text","marks":[{"type":"code"}]},{"text":" has ","type":"text"},{"text":"mcu_can__hw_handle_s","type":"text","marks":[{"type":"code"}]},{"text":")","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: ","type":"text"},{"text":"hal_spi__data_s;","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If the struct is the file/module name itself, we can omit the purpose.","type":"text"},{"type":"hardBreak"},{"text":"sl_ecu_info_s;","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Tag Pattern: ","type":"text"},{"text":"____tag","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"_","type":"text","marks":[{"type":"code"}]},{"text":" in the struct name must match the file name, unless the file is in format ","type":"text"},{"text":"__types","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: ","type":"text"},{"text":"hal_spi__data_tag","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If the struct is the file/module name itself, we can omit the purpose.","type":"text"},{"type":"hardBreak"},{"text":"sl_ecu_info_s;","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Tag is optional, but must follow this convention if included","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Struct member variables do not need layer or module name.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Initialization of structs:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Prefer trivial types at the beginning of your ","type":"text"},{"text":"struct","type":"text","marks":[{"type":"code"}]},{"text":". It is then easier to instantiate it like so: ","type":"text"},{"text":"struct_s s = { 0 };","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If you have a nested struct or union, and you want zero initialization, then putting trivial types at the beginning will result in safer code because you can initialize the first member and omit the other members to zero initialize themselves","type":"text"}]},{"type":"codeBlock","content":[{"text":" typedef struct {\n union {\n struct_a_s a;\n char string[32];\n };\n int member;\n } struct_s;","type":"text"}]},{"type":"paragraph","content":[{"text":"In the case above, the following notation will fail:","type":"text"}]},{"type":"codeBlock","content":[{"text":"// Compiler error on Linux: \"sorry, unimplemented: non-trivial designated initializers not supported\"\nstruct_s s = { .member = 123 };","type":"text"}]},{"type":"paragraph","content":[{"text":"Reorganizing the struct to put the union last like mentioned above will fix this issue.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The clang compiler does not like C++ ","type":"text"},{"text":":","type":"text","marks":[{"type":"code"}]},{"text":" initialization, such as ","type":"text"},{"text":"struct_s s = { foo: 0, bar: 1}","type":"text","marks":[{"type":"code"}]},{"text":", so do not use this method.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Not using dot initialization is dangerous because if someone changes the order of the members, it will create buggy code.","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":"struct_s s = { 123 };","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"However dot initialization or C++ ':' colon initialization does not work well for char arrays due to the following compiler error: 'C99 designator outside aggregate initializer'. Do to this initialization of a char array in a struct should be done like so:","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":"typedef struct {\n int x;\n char example_char_array[32];\n} example_s;\n\nexample_s s = {.x = 5};\nstrncpy(s.example_char_array, \"Hello World\", sizeof(s.example_char_array) - 1);","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Private data in structs","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If there is any data that you want to designate as ","type":"text"},{"text":"private","type":"text","marks":[{"type":"code"}]},{"text":" in a struct then simply store it in a internal struct named ","type":"text"},{"text":"private_data","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":"typedef struct {\n struct {\n int16_t private_data1;\n int32_t private_data2;\n } private_data;\n} struct_s;","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Unions","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Typedef Name Pattern: ","type":"text"},{"text":"___purpose_u","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"_","type":"text","marks":[{"type":"code"}]},{"text":" in the union name must match the file name, unless the file is in format ","type":"text"},{"text":"__types","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: ","type":"text"},{"text":"app_door__config_u;","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Tag Pattern: ","type":"text"},{"text":"___purpose_tag","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"_","type":"text","marks":[{"type":"code"}]},{"text":" in the union name must match the file name, unless the file is in format ","type":"text"},{"text":"__types","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: ","type":"text"},{"text":"app_door__config_tag","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Tag is optional, but must follow this convention if included","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Otherwise same as struct rules","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Function Pointers","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"typedef","type":"text","marks":[{"type":"code"}]},{"text":" Function Pointers if you use it more than once.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Typedef function pointer pattern: ","type":"text"},{"text":"____f","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"_","type":"text","marks":[{"type":"code"}]},{"text":" in the function pointer name must match the file name","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example: ","type":"text"},{"text":"typedef void (*hal_pwm__callback_f)(const uint8_t *data);","type":"text","marks":[{"type":"code"}]}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"While Loops","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"do while loops should ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" be used to keep consistency across modules. Use a while loop instead.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Macros","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"DO NOT USE MACROS","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Each macro use needs to be discussed with a team member before it is added","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoid macros at all costs.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"You must prove that a function is unable to achieve something before you create a function-like macro","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Most use cases of ","type":"text"},{"text":"#defines","type":"text","marks":[{"type":"code"}]},{"text":" can alternatively use ","type":"text"},{"text":"consts","type":"text","marks":[{"type":"code"}]},{"text":", which can be defined by library users in external modules.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Better alternatives to ","type":"text"},{"text":"#defines","type":"text","marks":[{"type":"code"}]},{"text":" are discussed below:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"const","type":"text","marks":[{"type":"code"}]},{"text":" for compiler switches","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Const supports unit testing whereas macros do not since they can not be modified in a test.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"To test a macro ","type":"text"},{"text":"#if ()","type":"text","marks":[{"type":"code"}]},{"text":" the code would have to be rewritten multiple times to test the alternative cases.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If a const variable is used, the variable can be altered.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"const","type":"text","marks":[{"type":"code"}]},{"text":" in place of ","type":"text"},{"text":"#defines","type":"text","marks":[{"type":"code"}]},{"text":" because it binds a type to the variable.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"There may be a genuine reason where const would not work, so treat this as an exception. For example:","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":"static const size_t MODULE_NAME__ARRAY_COUNT_INVALID = 2;\n#define MODULE_NAME__ARRAY_COUNT_VALID (2U)\nuint8_t array[MODULE_NAME__ARRAY_COUNT_INVALID]; // ← Compiler error if global\nuint8_t array[MODULE_NAME__ARRAY_COUNT_VALID];","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Note that even for the case above, the following is preferred if the const is only used for the array size:","type":"text"}]}]}]},{"type":"codeBlock","content":[{"text":"typedef uint8_t module_name__array_t[2U];","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Functions","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Only define function-like macros at ","type":"text"},{"text":"sl_function_macros.h","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"You will get scrutinized if you wish to add more macros to this file","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Prefer to use real functions, and do not optimize unless you perform timing analysis and can prove a macro is better than a function for a specific use case","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"It may be okay to create macros as replacements of C++ template types, such as ","type":"text"},{"text":"MIN_OF()","type":"text","marks":[{"type":"code"}]}]}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Macro guidelines","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Macros should always be UPPER CASE","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"#define MY_MACRO_ALL_CAPS_WITH_UNDERSCORES (42)","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Macros shall be parenthesized in their definition to prevent someone from accidentally mis-using it. For example:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"#define MIN_OF (a, b) (a < b) ? a : b // THIS IS BAD","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"#define MIN_OF (a, b) (((a) < (b)) ? (a) : (b)) // THIS IS GOOD","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"if","type":"text","marks":[{"type":"code"}]},{"text":" macro statements should always follow the pattern: ","type":"text"},{"text":"#if (...)","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example with multiple conditions: ","type":"text"},{"text":"#if ((...) && (...))","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Avoid using ","type":"text"},{"text":"#ifdef MACRO","type":"text","marks":[{"type":"code"}]},{"text":" when ","type":"text"},{"text":"#if MACRO","type":"text","marks":[{"type":"code"}]},{"text":" can be used","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"#define MACRO 0","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"#if MACRO // this is clear","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"#ifdef MACRO // this is not clear because it is not dependent on the actual value of MACRO","type":"text","marks":[{"type":"code"}]}]}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Macro invocations ","type":"text"},{"text":"do not","type":"text","marks":[{"type":"strong"}]},{"text":" need to be surrounded in parentheses.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Example:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"#if FEATURE_UDS // This is perfectly fine","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"#if (FEATURE_WINDOWS) // This isn't required because the macro itself should be written defensively so that it doesn't cause a problem if those parentheses are missing","type":"text","marks":[{"type":"code"}]}]}]}]}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Macros as compile-time switches","type":"text"}]},{"type":"paragraph","content":[{"text":"Macros used for compile-time switching should be treated as boolean values. This means that a macro should either be defined as ","type":"text"},{"text":"0","type":"text","marks":[{"type":"code"}]},{"text":" to disable the feature or ","type":"text"},{"text":"1","type":"text","marks":[{"type":"code"}]},{"text":" to enable it.","type":"text"}]},{"type":"paragraph","content":[{"text":"Reference the following code of an arbitrary file, such as ","type":"text"},{"text":"socket_proxy.c","type":"text","marks":[{"type":"code"}]},{"text":". Note that you want to avoid:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"#ifdef","type":"text","marks":[{"type":"code"}]},{"text":" because if the user defines the macro as ","type":"text"},{"text":"0","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"#ifdef","type":"text","marks":[{"type":"code"}]},{"text":" will still be true as the macro is defined.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"You want to switch on ","type":"text"},{"text":"#if FEATURE !=0","type":"text","marks":[{"type":"code"}]},{"text":" rather than ","type":"text"},{"text":"#ifdef FEATURE","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Compare values of the ","type":"text"},{"text":"#if","type":"text","marks":[{"type":"code"}]},{"text":" explicitly","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Example: ","type":"text"},{"text":"socket_proxy.c","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]},{"type":"codeBlock","content":[{"text":"/**\n * Start by defining your 'default'\n * This allows the build system to override the default\n */\n#ifndef MODULE_NAME__USE_POLL_API\n#define MODULE_NAME__USE_POLL_API (1)\n#endif\n\n/**\n * Check that the define is picked up by the compiler before you use the compiler switch\n */\n#ifndef MODULE_NAME__USE_POLL_API\n#error \"MODULE_NAME__USE_POLL_API must be defined\"\n#endif\n\n/**\n * Example usage of the macro\n * Note that the #endif indicates what #if we are ending\n */\nstatic int wait_for_read(int socket, uint32_t timeout_ms) {\n int return_code = -1;\n\n#if MODULE_NAME__USE_POLL_API\n struct pollfd poll_socket_read = {.fd = socket, .events = POLLIN};\n return_code = poll(&poll_socket_read, 1, timeout_ms);\n#else\n // ...\n return_code = select((socket + 1), &set, NULL, NULL, &timeout);\n#endif /* MODULE_NAME__USE_POLL_API */\n\n return return_code;\n}\n","type":"text"}]},{"type":"rule"},{"type":"heading","attrs":{"level":1},"content":[{"text":"Other Guidelines","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"String Literals in Print Statements","type":"text"}]},{"type":"paragraph","content":[{"text":"When using ","type":"text"},{"text":"printf(const char *format, ...)","type":"text","marks":[{"type":"code"}]},{"text":" or its variants, string literals should be used for the ","type":"text"},{"text":"format","type":"text","marks":[{"type":"code"}]},{"text":" parameter as opposed to a ","type":"text"},{"text":"char *","type":"text","marks":[{"type":"code"}]},{"text":" variable. The reason is because the compile can check the string literal’s ","type":"text"},{"text":"%","type":"text","marks":[{"type":"code"}]},{"text":" symbols, and match them against the number of arguments passed into ","type":"text"},{"text":"printf()","type":"text","marks":[{"type":"code"}]},{"text":" variants. The consequence of not matching the parameters with ","type":"text"},{"text":"%","type":"text","marks":[{"type":"code"}]},{"text":" symbols is stack corruption, hence, the compiler checks are vital for this use-case.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c"},"content":[{"text":"int value = 1;\n\n// Good\nprintf(\"Value is %d\", value);\n\n// Bad\nconst char* const format = \"Value is %d\";\nprintf(format, value);","type":"text"}]},{"type":"rule"},{"type":"heading","attrs":{"level":1},"content":[{"text":"Code Templates","type":"text"}]},{"type":"paragraph","content":[{"text":"The empty lines between includes, and their order is very important. The ","type":"text"},{"text":"clang-format","type":"text","marks":[{"type":"code"}]},{"text":" will re-order ","type":"text"},{"text":"#includes","type":"text","marks":[{"type":"code"}]},{"text":" if they are not ordered correctly.","type":"text"}]},{"type":"paragraph","content":[{"text":"The templates follow the ","type":"text"},{"text":"Order of Includes","type":"text","marks":[{"type":"link","attrs":{"href":"https://sibros.atlassian.net/wiki/spaces/SF/pages/62652558/C+Coding+Standards#Order-of-Includes"}}]},{"text":" and we do not duplicate the reasons here.","type":"text"}]},{"type":"paragraph","content":[{"text":"We use these templates with the ","type":"text"},{"text":"d3vnu1l.template-generator-vscode","type":"text","marks":[{"type":"code"}]},{"text":" plugin for VSCode, hence the macros enclosed within ","type":"text"},{"text":"{...}","type":"text","marks":[{"type":"code"}]},{"text":" seen below.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Header File","type":"text"}]},{"type":"codeBlock","content":[{"text":"/***********************************************************************************************************************\n * SIBROS TECHNOLOGIES, INC. CONFIDENTIAL\n * Copyright (c) 2018 - 2021 Sibros Technologies, Inc.\n * All Rights Reserved.\n * NOTICE: All information contained herein is, and remains the property of Sibros Technologies, Inc. and its suppliers,\n * if any. The intellectual and technical concepts contained herein are proprietary to Sibros Technologies, Inc. and its\n * suppliers and may be covered by U.S. and Foreign Patents, patents in process, and are protected by trade secret or\n * copyright law. Dissemination of this information or reproduction of this material is strictly forbidden unless prior\n * written permission is obtained from Sibros Technologies, Inc.\n **********************************************************************************************************************/\n\n/**\n * @file\n * Brief information about the code module\n *\n * Thread Safety Assessment:\n * \n * \n */\n\n#ifndef SIBROS__{__upperCaseName__}_H\n#define SIBROS__{__upperCaseName__}_H\n\n#ifdef __cplusplus\nextern \"C\" {\n#endif\n\n/***********************************************************************************************************************\n *\n * I N C L U D E S\n *\n **********************************************************************************************************************/\n/* Standard Includes */\n\n/* External Includes */\n\n/* Module Includes */\n\n/***********************************************************************************************************************\n *\n * D E F I N E S\n *\n **********************************************************************************************************************/\n\n/***********************************************************************************************************************\n *\n * T Y P E D E F S\n *\n **********************************************************************************************************************/\n\n/***********************************************************************************************************************\n *\n * F U N C T I O N D E C L A R A T I O N S\n *\n **********************************************************************************************************************/\n\n#ifdef __cplusplus\n} /* extern \"C\" */\n#endif\n\n#endif /* #ifdef SIBROS__{__upperCaseName__}_H */\n","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Private Header File","type":"text"}]},{"type":"codeBlock","content":[{"text":"/***********************************************************************************************************************\n * SIBROS TECHNOLOGIES, INC. CONFIDENTIAL\n * Copyright (c) 2018 - 2021 Sibros Technologies, Inc.\n * All Rights Reserved.\n * NOTICE: All information contained herein is, and remains the property of Sibros Technologies, Inc. and its suppliers,\n * if any. The intellectual and technical concepts contained herein are proprietary to Sibros Technologies, Inc. and its\n * suppliers and may be covered by U.S. and Foreign Patents, patents in process, and are protected by trade secret or\n * copyright law. Dissemination of this information or reproduction of this material is strictly forbidden unless prior\n * written permission is obtained from Sibros Technologies, Inc.\n **********************************************************************************************************************/\n\n#ifndef SIBROS__{__upperCaseName__}_PRIVATE_H\n#define SIBROS__{__upperCaseName__}_PRIVATE_H\n\n#ifdef __cplusplus\nextern \"C\" {\n#endif\n\n/***********************************************************************************************************************\n *\n * I N C L U D E S\n *\n **********************************************************************************************************************/\n/* Standard Includes */\n\n/* External Includes */\n\n/* Module Includes */\n#include \"sl_unit_test_facilitator.h\"\n\n/***********************************************************************************************************************\n *\n * D E F I N E S\n *\n **********************************************************************************************************************/\n\n/***********************************************************************************************************************\n *\n * T Y P E D E F S\n *\n **********************************************************************************************************************/\n\n/***********************************************************************************************************************\n *\n * P R I V A T E D A T A D E C L A R A T I O N S\n *\n **********************************************************************************************************************/\n\n/***********************************************************************************************************************\n *\n * F U N C T I O N D E C L A R A T I O N S\n *\n **********************************************************************************************************************/\n\n#ifdef __cplusplus\n} /* extern \"C\" */\n#endif\n\n#endif /* #ifdef SIBROS__{__upperCaseName__}_PRIVATE_H */\n","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Source File","type":"text"}]},{"type":"codeBlock","content":[{"text":"/***********************************************************************************************************************\n * SIBROS TECHNOLOGIES, INC. CONFIDENTIAL\n * Copyright (c) 2018 - 2021 Sibros Technologies, Inc.\n * All Rights Reserved.\n * NOTICE: All information contained herein is, and remains the property of Sibros Technologies, Inc. and its suppliers,\n * if any. The intellectual and technical concepts contained herein are proprietary to Sibros Technologies, Inc. and its\n * suppliers and may be covered by U.S. and Foreign Patents, patents in process, and are protected by trade secret or\n * copyright law. Dissemination of this information or reproduction of this material is strictly forbidden unless prior\n * written permission is obtained from Sibros Technologies, Inc.\n **********************************************************************************************************************/\n\n/***********************************************************************************************************************\n *\n * I N C L U D E S\n *\n **********************************************************************************************************************/\n/* Main Module Header */\n// #include \"{__name__}.h\"\n\n/* Standard Includes */\n\n/* External Includes */\n\n/* Private Module Includes */\n// #include \"{__name__}_private.h\" // either this\n// #include \"sl_unit_test_facilitator.h\" // or this\n\n/***********************************************************************************************************************\n *\n * D E F I N E S\n *\n **********************************************************************************************************************/\n\n/***********************************************************************************************************************\n *\n * T Y P E D E F S\n *\n **********************************************************************************************************************/\n\n/***********************************************************************************************************************\n *\n * P R I V A T E F U N C T I O N D E C L A R A T I O N S\n *\n **********************************************************************************************************************/\n\n/***********************************************************************************************************************\n *\n * P R I V A T E D A T A D E F I N I T I O N S\n *\n **********************************************************************************************************************/\n\n/***********************************************************************************************************************\n *\n * P R I V A T E F U N C T I O N S\n *\n **********************************************************************************************************************/\n\n/***********************************************************************************************************************\n *\n * P U B L I C F U N C T I O N S\n *\n **********************************************************************************************************************/\n","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Test File","type":"text"}]},{"type":"codeBlock","content":[{"text":"/***********************************************************************************************************************\n * SIBROS TECHNOLOGIES, INC. CONFIDENTIAL\n * Copyright (c) 2018 - 2021 Sibros Technologies, Inc.\n * All Rights Reserved.\n * NOTICE: All information contained herein is, and remains the property of Sibros Technologies, Inc. and its suppliers,\n * if any. The intellectual and technical concepts contained herein are proprietary to Sibros Technologies, Inc. and its\n * suppliers and may be covered by U.S. and Foreign Patents, patents in process, and are protected by trade secret or\n * copyright law. Dissemination of this information or reproduction of this material is strictly forbidden unless prior\n * written permission is obtained from Sibros Technologies, Inc.\n **********************************************************************************************************************/\n\n/***********************************************************************************************************************\n *\n * I N C L U D E S\n *\n **********************************************************************************************************************/\n/* Standard Includes */\n#include \"unity.h\"\n\n/* Mock Includes */\n\n/* External Includes */\n\n/* Module Includes */\n// #include \"{__name__}.h\"\n// #include \"{__name__}_private.h\" // either this\n// #include \"sl_unit_test_facilitator.h\" // or this\n\n/***********************************************************************************************************************\n *\n * D E F I N E S\n *\n **********************************************************************************************************************/\n\n/***********************************************************************************************************************\n *\n * T Y P E D E F S\n *\n **********************************************************************************************************************/\n\n/***********************************************************************************************************************\n *\n * P R I V A T E F U N C T I O N D E C L A R A T I O N S\n *\n **********************************************************************************************************************/\n\n/***********************************************************************************************************************\n *\n * P R I V A T E D A T A D E F I N I T I O N S\n *\n **********************************************************************************************************************/\n\n/***********************************************************************************************************************\n *\n * P R I V A T E F U N C T I O N S\n *\n **********************************************************************************************************************/\n\n/***********************************************************************************************************************\n *\n * T E S T S E T U P & T E A R D O W N\n *\n **********************************************************************************************************************/\n\nvoid setUp(void) {}\n\nvoid tearDown(void) {}\n\n/***********************************************************************************************************************\n *\n * T E S T S\n *\n **********************************************************************************************************************/\n\nvoid test_simple(void) {}","type":"text"}]},{"type":"paragraph"}],"version":1}

Browser not supported