Best Practices

Table of Contents

• Use issues to discuss intended modifications
• Document your code
• Coding style
• External tools and libraries
• MPI wrappers
• 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.

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.

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.