Good practice for functions release

From OpenFLUID

Good development practice

Use coding style guidelines

In order to produce clean code, read and apply coding style guidelines. Following these guidelines will increase the ability for others to understand and review your source code. th source code quality will be increased too.

Raise warnings an errors

While checking possible errors or warnings, give information about these failed tests using the OpenFLUID_RaiseWarning and OpenFLUID_RaiseError methods.

// ...
 
  BEGIN_SU_ORDERED_LOOP(SU)
 
    ID = SU->getID();
    OPENFLUID_GetVariable(SU,"input_var",CurrentStep,&TmpValue);
 
    if (TmpValue > 0)
    {
      ResultValue = 1/TmpValue;
      OPENFLUID_AppendVariable(SU,"output_var",ResultValue);
    }
    else
    {
      OPENFLUID_RaiseError("docfunction",CurrentStep,input_var is 0");
      return false;
    }    
 
  END_LOOP
 
// ...

Review code

Don't hesitate to view and review your source code to track errors, especially in tricky code parts. Use peer-reviewing if possible!

Good documentation practice

In order to ease the documentation production, the ofefunc2doc tool can extract documentation information directly from the source code. See also Building documentation from functions source code.

Give scientific information

Scientific information is really important for an adapted use of the simulation function you wrote. You can include scientific information in your source code as C comments. It is an easy way to maintain an up-to-date documentation, according to your source code.

Give usage information

Usage information will explain how to use the simulation functions, the input and output variables, the uses input data, the used parameters. A good usage information will increase the useness of the function, and the modelling work efficiency.

Good function signature practice

The signature is the visible part of the function. It summarizes the simulation function behaviour and should be filled with attention

Use naming conventions

In order to avoid naming conflicts with different simulation functions, please refer to the naming conventions. It will also clarify the names of functions and variables, that should be fully understandable by anyone having read the naming conventions.

Don't forget data units

Data units can cause numeric errors, so fill the data units correctly to avoid conversions errors for a variable used by different functions.

Good data consistency practice

Data consistency checking can avoid numerical errors in computational codes. Developers are encouraged to check data before using it and before producing it.

Check input data

Input data should be checked by simulation functions in order to verify if they match the correct values range. This should be done in the checkConsistency method of the function.

bool ExampleFunc::checkConsistency()
{
  openfluid::core::ScalarValue Ks;
  openfluid::core::SurfaceUnit* SU;
  DECLARE_SU_ORDERED_LOOP
 
  BEGIN_SU_ORDERED_LOOP(SU)
 
    OPENFLUID_GetProperty(SU,"ks",&Ks);
 
    if (KS < 0)
    {
      std::string IDStr;
      openfluid::tools::ConvertValue(ID,&IDStr);
      OPENFLUID_RaiseError("example.func","Negative ks on SU " + IDStr);
    }
 
  END_LOOP
}

Check variables before production

Produced variables should be checked before producing it in order to avoid out of range or NaN values that can cause errors later or in other functions.

Good testing practice

Testing is the better way to check and validate simulation functions. There is no limit for testing!

Use standard tests

Test your simulation functions with the most commonly used conditions, in order to check if the function response is correct. These condituions should be the common usage of the function.

Use crash tests

Test your simulation functions with extreme condition, using the lower and higher values of the possible values range. The function should work without crash in these condition, or produce warnings and error if necessary.