Best Practices and Style

The fortran-lang style guide asks for three things: write the keywords and constructs (do, subroutine, module) in lower case; use lower case for other names, keep them short, ideally one or two syllables, and separate longer words with underscores; and indent consistently, where the guide leaves the width to taste (two, three or four spaces are all common). It prefers standard mathematical notation for mathematical symbols and warns against abbreviations that are ambiguous: spline_interp is acceptable, splineint is not. The stdlib guide is stricter and is the better template for a library: four spaces of indentation and no tabs, lines of 80 characters or fewer with 132 as a hard limit, intent on every dummy argument, optional written after intent, at most one program, module or submodule per file, the file named after the unit with the extension .f90 (or .F90 when it is preprocessed), and the unit name repeated on the end statement unless the block is short.

Fortran itself is case-insensitive, so none of this is enforced by a compiler. The language does impose a few limits that a style should stay well inside of. A name has at most 63 characters (C601 in 6.2.2), and a free-form line has at most ten thousand characters in Fortran 2023 (6.3.2.1); the older limit of 132 characters is the figure the style guides still use as a portable upper bound for readability and for older compilers. The detailed rules of source form are in Program Structure and Source Form.

The recommended style in one place, in the module that holds the example for the rest of this page:

Output with gfortran 16.2 and with Flang 23 (identical):

The module compiled without a warning under -std=f2023 -Wall -Wextra -pedantic -fcheck=all and with Flang 23.

Source: J3/23-007r1: 6.2.2 Names, 6.3.2 Free source form, 15.7 Pure procedures, 15.9 Elemental procedures, Fortran Programming Language: Best Practices, Fortran Style Guide and Fortran stdlib: Style guide

What the module shows, rule by rule:

Fortran 77 gave every undeclared name a type from its first letter, and that rule still exists unless it is switched off. The statement implicit none (8.7) switches it off for a scoping unit; the Fortran 2018 form implicit none (type, external) also requires every external procedure to be declared (the GNU Fortran status page for Fortran 2018 lists the implicit-none-spec-list as supported). implicit none in a module applies to every procedure the module contains and to its submodules, so one statement per module is enough, and every main program needs its own. In this guide’s modules it is the first statement after the use statements.

A misspelled variable is the classic case. This program is legal Fortran with implicit typing, and prints a wrong answer without any message:

Built with plain gfortran 01_typo.f90 and run:

The assignment to resdual created a new real variable and the real result residual was never updated. With implicit none, or with the flag -fimplicit-none that fpm and the verification script pass to GNU Fortran, the same program does not compile. These are the real messages:

(gfortran 16.2), and for Flang 23, built with flang-23 -fimplicit-none:

Source: J3/23-007r1: 8.7 IMPLICIT statement and B.3.15 of the J3/26-007r1 draft

The external half of the statement catches the call to a procedure that nobody declared. With implicit none (type, external) the call below is an error instead of a link-time problem or, worse, a call with a mismatched argument list:

gfortran 16.2 (-std=f2023) reports:

and Flang 23:

Source: J3/23-007r1: 8.7 IMPLICIT statement and B.3.15 of the J3/26-007r1 draft, GNU Fortran manual: Fortran 2018 status and Options controlling Fortran dialect

The 2028 draft goes one step further: J3/26-007r1 lists default implicit typing among the obsolescent features (B.3.15 of that draft; see What’s New and Fortran 2028 Preview). That document is a committee draft, not a standard. Writing implicit none now makes a program immune to the change. For the same reason fpm projects set implicit-typing = false and implicit-external = false in the [fortran] table of fpm.toml, as heatflow does (Fortran Package Manager (fpm)); a plain fpm build of the sources already passes -fimplicit-none to GNU Fortran.

Never write real*8, double precision, or rely on the default real having a particular precision. Define the kinds once in a module, import only the names needed, and give every literal the kind of the variable it initializes. The heatflow kinds module is the whole mechanism:

Source: J3/23-007r1: 16.10.2.1 The ISO_FORTRAN_ENV intrinsic module and 16.9.183 SELECTED_REAL_KIND, Fortran Programming Language: Best Practices, Floating Point Numbers

The kind constants of iso_fortran_env (real32, real64, real128, int32, …​) are a portable way to ask for a storage size; selected_real_kind(p, r) asks for a precision and range instead. The two models, their pitfalls, and the fact that a requested kind may not exist (real128 is a negative constant on a compiler that does not provide it) are in Intrinsic Types and Kinds and Intrinsic Modules and iso_fortran_env.

The literal is the part people forget. 0.1 is a default-real constant, which is converted to double precision after it has been rounded to single precision:

gfortran 16.2 and Flang 23 print the same digits:

The compilers disagree on how loudly they complain. GNU Fortran says nothing under -Wall -Wextra; it needs -Wconversion-extra:

Flang 23 warns by default, with a message that names the exact value that is lost:

Source: J3/23-007r1: 7.4.3.2 Real type and 10.1.5.2 Numeric intrinsic operations, GNU Fortran manual: Options to request or suppress errors and warnings

Two further habits belong here. First, do not use -fdefault-real-8 (or the equivalent in other compilers) to fix a legacy code base: it changes the kind of every default real, including the ones in calls to libraries that expect a default real, and the standard’s rules about double precision stay true only by accident. Second, never compare reals with == unless equality is exactly what is meant; -Wcompare-reals warns about it, and the floating-point page has the correct comparisons (Floating-Point and IEEE Arithmetic).

intent(in), intent(out) and intent(inout) (8.5.10) say how a dummy argument is used. They are not decoration: the compiler rejects a write to an intent(in) dummy, and an intent(out) dummy is undefined on entry (and its allocatable parts are deallocated, its defaulted components are initialized), which the optimizer can exploit. Missing an intent is not an error, and no warning flag asks for it, so the rule has to be a house rule enforced in review or by a linter (see Let the compiler review the code). The real diagnostics when the rule is broken:

gfortran 16.2:

Flang 23:

Source: J3/23-007r1: 8.5.10 INTENT attribute and 15.5.2.4 Argument association

An intent(out) argument that is never set is detected by -Wall in GNU Fortran, together with an unused local variable:

Compiling with gfortran -std=f2023 -Wall -Wextra -pedantic:

and the program, which is legal, prints the following (the single-precision constant 0.25 is silently widened; it is exactly representable, so the answer is right, but -Wconversion-extra flags it as in the previous section):

Source: J3/23-007r1: 8.5.10 INTENT attribute and 15.5.2.4 Argument association, GNU Fortran manual: Options to request or suppress errors and warnings

A procedure that has no side effects should say so with pure (15.7), and one that acts on every element of an array argument identically should be elemental (15.9; an elemental procedure is pure unless it says impure). The payoff is concrete: a pure procedure may be called from a do concurrent construct and from another pure procedure, an elemental one works on a scalar and on arrays of any rank with one definition (relative_change above is called with rank-1 arrays), and the compiler enforces the contract. The restrictions are checked: a pure procedure may not assign to a module variable.

gfortran 16.2:

Flang 23:

Source: J3/23-007r1: 15.7 Pure procedures and 15.9 Elemental procedures

The pure kernels of heatflow (jacobi_sweep, ftcs_sweep) are the same discipline applied to a numerical core. Do not mark everything pure for its own sake: a routine that must print, read a file or measure time cannot be, and the Fortran 2018 permission for error stop in a pure procedure (Error Handling and Program Termination) is meant for assertion failures, not for control flow. Use value (8.5.19) only for scalars passed by value, mainly for C interoperability (Interoperability with C).

Every procedure belongs in a module (or is an internal procedure): a module procedure has an explicit interface by construction, so the compiler checks every call, and no interface block ever has to be written by hand and kept in sync. Three habits make the module a good unit of design:

Here is what the compiler says about the missing only clause (GNU Fortran, -Wuse-without-only, not part of -Wall), for the program in 02_unused_and_conversion.f90:

The cost of omitting it is paid later, when two modules export the same name; that failure, with the real diagnostic, is in Modules and Submodules. A subtle point: a bare private in a module also applies to names the module merely uses, so a module that needs to re-export a kind must say so with a public statement; the heatflow kinds module does exactly that with public :: sp, dp, ip, lp.

Source: J3/23-007r1: 8.5.2 Accessibility attribute, 8.6.1 Accessibility statement and 14.2.2 The USE statement and use association, Fortran Programming Language: Best Practices, Modules and programs

When an interface must stay stable while the implementation changes, the module declares the interface and a submodule supplies the body. heatflow does this for its solvers: heatflow_solver holds the abstract solver_t and the interfaces, and the submodules heatflow_jacobi and heatflow_ftcs implement the steps, so changing a numerical scheme does not recompile the code that uses the module.

Prefer allocatable for dynamic memory. An allocatable object is deallocated automatically when it goes out of scope, it cannot be aliased, it can be copied by assignment (with automatic reallocation) and a function can return it. A pointer can point at anything with the target attribute and at arbitrary heap memory, which is sometimes exactly what is needed (linked structures, views of a subobject; see Pointers and Targets), but it is never freed unless someone remembers to.

The next program calls a function that returns an allocatable array a thousand times and one that returns a pointer a thousand times. The first needs no cleanup code; the second leaks every call.

Both compilers print the same total:

Running the gfortran build (gfortran -g -O0) under Valgrind 3.x in the verification container, filtered to the summary lines:

The 1,000 lost blocks are exactly the pointer results; the allocatable results were all freed. (The block and byte counts are those of this run and depend on the runtime.)

Source: J3/23-007r1: 8.5.3 ALLOCATABLE attribute, 8.5.14 POINTER attribute and 9.7.3.2 Deallocation of allocatable variables, Fortran Programming Language: Best Practices, Allocatable Arrays, Valgrind Memcheck manual

Related advice: use assumed-shape (real(dp), intent(in) :: u(:, :)) dummies rather than explicit-size or assumed-size ones, and let size(u, 1) give the extent, as the heatflow kernels do (Array Arguments: Assumed Shape, Size and Rank); use whole-array operations and intrinsics instead of loops where they are clearer (Array Intrinsics and Reductions); and when the order of loops matters for speed, write the first index innermost (Performance and Memory Layout).

A module variable has the save attribute implicitly (8.5.16): it lives for the whole run and every user of the module sees the same one. That is occasionally right (a table that is read-only after initialization, a named constant) and usually a trap: the procedures that touch it are no longer pure, cannot be called concurrently, and give different answers on identical arguments. The alternative is to put the state in a derived type and pass the object:

Output of both compilers:

The global counter has no owner: relax_global bumped it twice behind the caller’s back and the third call to tick returns 3. The explicit counters are per object and each routine’s effect is visible in its argument list. The same reasoning applies to common blocks, whose use is legacy (Legacy Features and Modernization), and to variables with save: if a state must be shared, make it a component of a type that the caller creates, and if the state is protected configuration, protected (8.5.15) lets users read it without being able to change it.

Source: J3/23-007r1: 8.5.15 PROTECTED attribute, 8.5.16 SAVE attribute and 15.7 Pure procedures

Also keep module variables out of default initialization traps: an initialization in a declaration of a local variable (integer :: n = 0) implies save and runs only once, which is the single most common surprise in this area (Common Gotchas and Pitfalls).

A reusable procedure should not decide that the program must die. The policy that composes well:

Run with gfortran 16.2; the program’s own output is on standard output, the diagnostic on standard error, and the exit status is 2:

(The addresses of the backtrace are omitted here, they change from run to run.) Flang 23 prints Fortran ERROR STOP: code 2 followed by IEEE arithmetic exceptions signaled: INEXACT and also exits with status 2; the second line is the runtime’s report of the floating-point flags that were raised and has nothing to do with the program’s fault. The details of stop, error stop, iostat, iomsg and the exit codes are in Error Handling and Program Termination, and the same policy for file operations in Input/Output: Units and Files.

Source: J3/23-007r1: 11.4 STOP and ERROR STOP statements and 9.7.1 ALLOCATE statement

The strictest tool is the compiler that will build the program in production, run with its checking options during development. The set used to check every example on these pages is -std=f2023 -Wall -Wextra -pedantic -fimplicit-none -fcheck=all -g -fbacktrace. -std=f2023 makes non-standard syntax an error; -fcheck=all adds run-time bounds, pointer, recursion and allocation checks; -Wall -Wextra are the warnings that rarely produce noise. A few warnings are off by default and worth enabling for library code (all of these flags exist in GNU Fortran 16.2):

Flang has its own switches; its default warnings already include the literal-widening message shown above, and flang --help is the reference. Recommended option sets for developer, CI, release and cluster builds, with the evidence behind each flag, are in Compilers and Compiler Options. A caveat that surprises many projects: a plain fpm build of fpm 0.13.0 passed no warning or run-time-check flags apart from -fimplicit-none and -Werror=implicit-interface; the profile has to be named (fpm build --profile debug) to get them (Fortran Package Manager (fpm)).

Formatting is better done by a tool than by review. fprettify (community, Python) and findent re-indent and normalise spacing; linters such as Fortitude check rules that a compiler does not. They are community tools with their own options and versions, and their use, configuration and the diffs they produce are in Documentation and Editor Tooling. Whatever is chosen, run it in CI, so that the style rules are not a matter of opinion in review. Tests belong to the same discipline: a failing test is a better reviewer than a warning (Testing, Debugging and Profiling).

An fpm project is the simplest layout that satisfies every rule above: library sources under src/, the command-line program under app/, tests under test/, examples under example/, and a manifest fpm.toml. The heatflow project in the verification directory looks like this (build directories and generated files omitted; parallel/, python/ and mex/ hold the C, MPI, coarray, OpenMP, f2py and MATLAB variants that other pages build by hand):

Design rules that this layout expresses:

The fpm manifest that goes with it, shortened to what matters for style:

Source: fpm manifest reference and Fortran stdlib: Style guide

If the library will also be built with CMake or Meson, keep the same layout and let each build system glob or list the src/ files; heatflow/CMakeLists.txt in the verification project does so. Versioning, installation and the registry are in Fortran Package Manager (fpm).

Document every public and protected entity and each of its arguments, as the stdlib guide asks. The tool is FORD, which reads comments that start with !> (before an entity) or !! (after it, or at the end of a declaration line), takes Markdown, recognises @note, @warning and @todo, and generates a site with call graphs. A short comment that says what the procedure does and which conditions it requires is worth more than a long one that repeats the declaration. The !> comments in the modules of this page are of this kind. FORD’s installation, project file, graphs, the exact comment forms (checked against FORD 7.0.13) and the fortls language server are in Documentation and Editor Tooling; nothing in the standard defines documentation comments.

One of the two reference books on modern Fortran closes with an appendix that lists constructs its authors recommend against, under the heading of deprecated features. That list is useful advice and is repeated here, but it is not the standard’s: the standard maintains its own lists of deleted and obsolescent features in Annex B, and most of the constructs below are fully current. The table separates the two. The "Annex B status" column was checked against Annex B of J3/23-007r1 (B.1 deleted from Fortran 90, B.2 deleted from Fortran 2008, B.3 obsolescent).

The obsolescent list of the standard itself is: alternate return, computed go to, statement functions, data statements among executable statements, assumed-length character functions, fixed source form, character* declarations, entry, labelled do, common, equivalence and block data, the specific names of intrinsic functions, and forall (B.3.2 to B.3.13). Arithmetic if and the non-block do construct are listed in B.2 as deleted Fortran 2008 features; B.1 lists the real and double-precision do variable, pause, assign and assigned go to, the H edit descriptor and vertical format control as deleted Fortran 90 features. Their treatment, with the old code shown and labelled as legacy and the modern replacement, is only in Legacy Features and Modernization.

Not checked here, because no compiler for them is installed: Intel ifx, NAG, HPE Cray and NVIDIA HPC compilers; see History, Standards and Compilers for the per-compiler support table.