Code

Bread Crumbs: Home - SW_Dev_Proc - Impl - Code
Source code creation should be performed in accordance with the project coding standard. Although the coding activity is sometimes regarded as the most important part of the entire software development process, it is in fact a translation from non-executable design information into executable artifacts, the source code files (via build tools which translate the human-readable source code into machine-readable binary).

It is important that coding is performed with fast and convenient access to design artifacts. The code is the realization of the design that is specified and modeled in those design artifacts. The design corresponds to the requirements and the code must correspond to the design in order to fulfill the requirements.

On this page, the following topics will be covered:

Coding Standard

Style Rules

Coding standards can improve the readability of source code during reviews by requiring code writers to adhere to certain coding style conventions. For reasons that I do not quite understand, this can sometimes become an emotionally charged issue. Some folks like to write "if" statements with the curly brace on the same line as the if statement. Others like to have the opening curly brace on the next line aligned with the 'i' of the "if" statement. Some people like to indent five spaces while others may only want to indent two spaces. It goes on and on. With a common style of coding, an organization can be accustomed to that style which will not only be useful during code reviews, but it will also assist in creating analysis tools that do things like parse source files across the entire source code tree to count the number of times a given set of functions are called. If some people like to have a space between the function name and the opening parenthesis whereas others want no spaces between, then it makes creating reliable analysis tools that must parse the disparate styles very difficult. Some organizations may elect to have a code formatter run against all source code before getting checked into source control. Other organizations may want to format the source code to a common format on the back end. By that, I mean that the source is stored in source control in its original format since it matches the author's natural style; however, the source file is processed by a "pretty printer" before any code reviews in order to give it a common style. A "pretty printer" is a utility that parses source files of various formats (coding styles) and prints them (either to a printer or another file) in a common format chosen by the organization for code reviews.

An example of some source code formatting requirements follow (these will often be influenced by the chosen programming language):

  • SR01: Indentation must be three spaces.

  • SR02: Scope opening character must be the first non-white space character on a line.

  • SR03: No lines are to exceed 80 characters in length.

  • SR04: Tabs are not allowed.

  • SR05: Every function must have a fully specified prolog.

  • SR06: Variable names must begin with lower-case.

  • SR07: Function names must begin with lower-case.

  • SR08: Class names must begin with upper-case.

  • SR09: Variable names must be at least four characters in length.

  • SR10: Function names must be at least six characters in length.

  • SR11: Never precede function names with an underscore character.

  • SR12: Never precede variable names with an underscore character.

  • SR13: For class, function, and variable names with multiple words, use mixed case notation such that each capital letter begins a new word in the name (with the exception of the first word for function names and variable names).

Coding Rules

Coding rules might at first seem similar to style rules, but should be more focused on correctly functioning code as opposed to code readability. Coding rules may vary, but there are some established, venerable rules that should always apply.

 An example of some coding rules follow (these will often be influenced by the chosen programming language as well as the target application domain):

  • CR01: Avoid using multiple inheritance. If it is deemed absolutely necessary, then it must be approved by the project team lead.

  • CR02: Do not throw exceptions from a destructor.

  • CR03: Avoid using goto statements. If it is deemed absolutely necessary, then it must be approved by the project team lead.

  • CR04: Avoid using recursion. If it is deemed absolutely necessary, then it must be approved by the project team lead.

  • CR05: Handle all branching conditions specifically. A trailing "else" of an "if-else" construct should always be an error case. Likewise, the "default" case of a "switch" construct should always be an error case.

  • CR06: Integer constants and integer literals that are used as state or flag values in logical statements must be differentiated from other flags / states in the same set by at least three bits.

  • CR07: Never mask error codes. If an error code is returned, do not discard that code and instead return a different error code.

  • CR08: Initialize all variables at declaration.

  • CR09: Avoid using global variables. If it is deemed absolutely necessary, then it must be approved by the project team lead.

  • CR10: Serialize all access to global variables if there is any possibility of multiple threads running concurrently.

  • CR11: All functions must have only one exit or return point.

  • CR12: Always check pointers for NULL before dereferencing those pointers.

  • CR13: Ensure that parameters that are not intended to be updated by the function that is getting called are given "const" qualifiers.

Note: The above rules are specific to the C and C++ programming languages.

No part of this work should be produced or used without the permission of the authors: Michael Turner and Dr. Sharon A White.