Close

Code Quality Guide

Software that is included in the OpenFOAM source code base must conform to quality standards. Software quality can be split into two areas:

  • Functional quality: how well it performs to a given design, based on requirements, i.e. its fitness for purpose.
  • Structural quality: how well it meets requirements to be able to deliver functional quality, through sound architecture, robustness, ease of maintenance, etc.

Functional quality affects primarily the user experience whereas structural quality mostly concerns the contributors. Quality requirements are not confined only to code but relate to anything that is included in OpenFOAM, e.g. scripts, configurations, example cases, documentation, etc.

Functional Quality

Functional quality can be assessed through software testing, both functional testing where the actions of individual functions are verified, or non-functional testing, where the ability of a solver to simulate a problem in CFD can be assessed, for example. In order to ensure functional quality the following issues must be addressed as part of any contribution.

  • Specification: In order to be able to assess functional quality, a specification of the functionality is required. Specifications for CFD software must follow sound principles of science and engineering.
  • Benefits: The benefits of new functionality must be assessed. Where a contribution build on existing functionality, it should offer some improvement to performance, accuracy, reliability, etc. Where functionality is entirely new, the need for the functionality should be addressed.
  • Usability: The functionality must be designed for convenient deployment and reasonable attempts made to enable users to adopt it, e.g. through example cases, template files, documentation, etc.
  • Impact on associated code: An assessment of the impact on associated code must be made. Does the new code impact performance of existing code? Does it supersede other code, and if so, is there a plan to deprecate the older code?
  • Testing: It is the responsibility of the contributor to provide relevant tests for the new functionality, to demonstrate the functionality meets the criteria listed above. Tests should be part of OpenFOAM, e.g. an example case, test app (see $FOAM_APP/test), to enable future testing and maintenance of the functionality.

Structural Quality

Structural quality relates to attributes that are more difficult to measure, such as maintainability, reliability and efficiency. Contributed code must conform to the standards of structural quality within the existing OpenFOAM code.

  • Maintainability: Effort must be taken to improve maintainability, including minimising code size and duplication, e.g. deriving new classes from existing classes, rather than duplicating existing classes; and targeting broad applicability, e.g. avoid highly specific coding for a particular simulation case.
  • Application Program Interface(s) (API): Just as we need to promote an intuitive user interface, developers require contributed code with an intuitive API where, as often as possible, the behaviour of code should be understandable from careful function naming, logical data structures, etc.
  • Consistency: Contributed code must be consistent with the rest of OpenFOAM, e.g. using OpenFOAM’s own container classes than those from the C++ Standard Template Library . Code must conform to the OpenFOAM coding style guidelines.
  • Design: High quality software design with the effective use of abstraction, modularity, data structures, overall architecture and design patterns.

Testing of structural quality occurs, in effect, as part of development and maintenance of the code.  Code with poor structural quality is generally inflexible and difficult to extend and maintain.  At some point, the only way to improve structural quality is to redesign and restructure code.  This is code rewrite, an activity that is essential to maintain high quality software, but in which only the best lead developers are generally willing to engage.