Firedrake coding guide

Coding style

• PEP 8 should be followed.
• f-strings should be preferred to the older style % and .format() string formatting methods. A possible exception to this is with large multi-line strings where .format() may be more readable.
• Excessively long functions (50 lines+) should ideally be broken apart into more readable pieces.

Type hinting

• Type hinting should be used throughout. It is not necessary in the test suite.

Type hinting tips + tricks

• To avoid issues with forward references (until Python 3.14) you should add the line from __future__ import annotations to the top of the file.
• To avoid issues with circular imports you should do

if typing.TYPE_CHECKING:
    from firedrake import Function  # assuming that this is a circular dependency

Docstrings

• PEP 257 (docstrings) should be followed.
• Docstrings should be written in numpydoc format. Since type hinting is used it is not necessary to specify the type of function arguments in the docstring (unfortunately the return type still needs to be documented, ref). Occasionally it is fine to have a different type description in the numpydoc if it would otherwise expose a complicated internal detail (e.g. WithGeometry vs FunctionSpace).

Existing code

If changes are made to existing code that does not already conform to this guide, then the code should be rewritten to be conforming as part of the change.

Other policies

• Untaped parts of the interface should raise an exception if taping is enabled (minutes)