While this process is primarily focused on model-based development, there is often a limited amount of
hand-written source code. The guidelines are primarily meant to ensure readability, understandability and testability
and therefore do not apply strongly to code automatically generated from the models, since in that case, the model is
generally the work product that will be reviewed.
Guidance here is provided for structuring, coding for testability, and in-line documentation (comments). Source-code
language-specific guidance is not provided here.
Code Structuring
Code structuring refers to the physical organization of source code into files as well as the organization of code
elements within the source files.
File Organization
For object-oriented source code, we recommend that there is a header and implementation file (e.g. .cpp and .h) for
every class and package. For structured code, we recommend that the contents within the file are strongly cohesive,
either/or around data, behavior, or functionality. In any event, if it is possible to multiply-include a file header,
then it should be explicitly prevented (such as with a #IFDEF in C or C++).
Comments
Each file should have a comment header identifying the following
-
The purpose of the file and its contents
-
A list and brief description of the primary elements within the file
-
Important preconditions or constraints on the elements of the file or their usage
-
Raised error code or exceptions
Each element (e.g. class, variable, type, or function) should be prefaced with a comment block that describes the
element, constraints, preconditions or limitations on its usage, post-conditions (where appropriate), and errors or
exceptions raised. For scalar data elements (scalar variables or scalar parameters), the comment should also identify
valid and invalid ranges and values, as well as what actions should be taken when the variable is out of range, if
known in the context.
Comments should always address why the element is structured or written as it is not what the
structure is (since that is apparent from the code itself).
Declarations
Whenever possible, a element should be declared before it is used. This is often done with "forward declarations".
Code Design for Readability
-
A consistent naming convention should be followed as well as consistent formatting.
-
Care should be taken to avoid writing code, which even though correct, is obscure and/or difficult to understand or
debug.
-
Indentation should be used consistently to show level of scope nesting (e.g. indent the content of a "function",
"loop", "if" or "case" statement)
-
Use blank lines to visually organize related code into blocks
-
Avoid using uncommented "magic names". When constants are required, name them and, if necessary explain them, e.g.
-
const double PI = 3.14159265;
-
#DEFINE RADAR_BIT_FAIL (0x3CC) /* Returned by the Radar device hardware when built in test fails */
-
Use named enumerations rather than numbers when possible
-
It is usually preferable to have code that is more readable than more optimal
-
When execution optimality is necessary and it makes the code less readable or understandable, be sure to
add additional comments to assist in the comprehension of the code
-
Avoid bit-packing attributes and variables unless required
Code Design for Correctness
-
Initialize each variable or attribute when it is constructed
-
Always check return values when present
-
Pointers to functions should be declared const
-
Static and global variables should be defined within a namespace to prevent name pollution
-
Static checking tool such as LINT should be run on code prior to its delivery to aid the identification of
potential problems (e.g. memory leaks)
Defensive Design
Defensive design is a principle in which you assume that the preconditions of the code you write will be violated and
explicitly check for and handle such situations
-
Always check parameter values to ensure they are in range and/or reasonable (e.g. an array index should not be
negative, the weight of a patient for a medical application will not exceed 1000 Kg, body temperature for a live
patient is in the range of room temperature to 120 degrees Fahrenheit).
-
Always handle exceptions and errors returned, unless the code does not have enough scope or context information to
do the corrective action
Code Design for Testability
-
Non-deliverable source code developed expressly to debug or unit test deliverable code should be put in separate
files and be configuration managed with the code that it debugs or tests.
-
Code should be explicitly tested for the following kinds of defects
-
Parameters or values out of range and other precondition violations
-
Parameters or values on the end points of a range (boundary tests)
-
High volume of data (stress test)
-
Quality of service (e.g. worst case performance)
-
Random in-range data values (statistical testing)
-
Code coverage (e.g. DC - decision coverage, or MCDC (Modified Condition Decision Coverage))
|