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. The source code quality will be increased too.
You can adopt the OpenFLUID coding style.

Raise warnings an errors

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

// ...

openfluid::core::SpatialUnit* SU;
openfluid::core::DoubleValue TmpValue, ResultValue;

OPENFLUID_UNITS_ORDERED_LOOP("SU",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("input_var is 0");

}

// ...

Review code

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

Good documentation practices

For easier production of scientific documentation, the sim2doc tool can extract documentation directly from the source code. See also how to buil documentation from simulators source code.

Give scientific information

Scientific information is really important for an adapted use of the simulator you developed. You can include scientific information in your source code as C/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 simulators, the input and output variables, the used attributes, the used parameters. A good usage information will increase the useness of the simulator and the modelling work efficiency.

Good practices for simulator signature

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

Use naming conventions

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

Do not forget data units

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

Good data consistency practices

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

Check attributes

Attributes should be checked by simulators in order to verify if they match the correct range of values. This should be done in the checkConsistency method of the simulator.

void ExampleFunc::checkConsistency()
{
  openfluid::core::DoubleValue Ks;
  openfluid::core::SpatialUnit* SU;

  OPENFLUID_UNITS_ORDERED_LOOP("SU",SU)
  {
    OPENFLUID_GetAttribute(SU,"ks",Ks);

    if (Ks < 0)
    {
      std::string IDStr;
      openfluid::tools::ConvertValue(ID,&IDStr);
      OPENFLUID_RaiseError("Negative ks on SU " + IDStr);
    }
  }
}

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 simulators.

Good testing practices

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

Use standard tests

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

Use crash tests

Test your simulators with extreme conditions, for example by testing the lower and higher values of the possible values range. The simulator should work without crash in these conditions, or produce warnings and error if necessary.