Best Practices

Table of Contents

• Use issues to discuss intended modifications
• Document your code
• Coding style
• Please do NOT use MPI BARRIERS unless you know exactly what you are doing
• External tools and libraries
• MPI wrappers
• Unit testing and regression testing
• Wiki usage

Use issues to discuss intended modifications

GitHub provides a system to track issues. It should be a central place to monitor SPECFEM3D evolution. In particular:

• report bug as they occur

• plan modifications.

The issue tracker interface lets us track bugs being fixed and enhancements being made by assigning labels. We will reserve the labels

• bug for issue fixing

• enhancement for feature development.

Document your code

Any new code should be fully Doxygen commented. If you have some free time, feel free to comment any code you modify.

Coding style

When modifying an existing file, try to maintain consistency with its original style. If the code you add looks drastically different from the original code, it may be difficult for readers to follow. Try to avoid this.

Please do NOT use MPI BARRIERS unless you know exactly what you are doing

In the past we sometimes got deadlocking in the code because of MPI_BARRIERS that were added recently inside "if" statements. This is pretty dangerous because if the "if" statement is true on some processors but not others the code deadlocks and the simulation becomes idle (forever).

Thus, please do not add MPI_BARRIERs unless you know exactly what you are doing (in 99% of the cases they are useless anyway).

In particular, never put them in "if" statements.

External tools and libraries

Important note for all developers: we should never use Release Candidate (rc) versions of any external package used by the SPECFEM codes, only stable versions. For instance, regarding SCOTCH, please do not use e.g. scotch_6.0.1rc2 but rather a stable version such as scotch_5.1.12b.

MPI wrappers

When programming new features or routines for SPECFEM3D or SPECFEM3D_GLOBE, if you need to use MPI, please do not call MPI directly but rather use the wrapper routines that you will find in file src/shared/parallel.f90.

Unit testing and regression testing

This section is just a stub.

Wiki usage

The Wiki is meant to be used as a developer reference, not a replacement for the user manual. In general, the Wiki should only contain entries on software engineering and computer science aspects of SPECFEM development.

Anyone with pull access to the central repository is allowed to make changes to the Wiki. Note that the Wiki is itself a Git repository that you can clone locally, modify with your favourite Markdown editor and push your changes to the remote server.