B.2 Commenting and style requests

Generally, no strong style conventions are enforced within FHI-aims, recognizing the fact that most programmers follow their own style conventions and preferences when it comes to details. There are, however, some conventions that should be followed in order to keep the code as a whole legible, and maintainable. When writing additional code, please adhere to these, using existing modules or subroutines as models where appropriate.

A current set of “code conventions” is maintained at the Wiki at https://aims-git.rz-berlin.mpg.de. A subset of these recommendations includes:

  1. 1.

    Please comment your work. Any necessary functionality should be accompanied with comments, enough so that at least someone familiar with the underlying mathematics can follow your code.

  2. 2.

    Please provide regular comment headers for your work. Every module and subroutine comes with comment headers in the style used by the Robodoc code management system (see, e.g., http://www.xs4all.nl/~rfsber/Robo for details and a manual). Beyond the possible use of Robodoc, we follow this convention because it provides a clear and unambiguous laundry list of items that are needed in any subroutine header: a description of the subroutine purpose, possibly its input and output data, and most importantly a copyright statement that is needed for every file in the code distribution.

  3. 3.

    Please keep your usage of Fortran conservative. Some ambitious constructs, while desirable when following formal techniques such as fully object-oriented programming, can still expose compiler bugs when too “un-Fortran-like” syntax is used.

  4. 4.

    In particular, compiler-dependent bugs are the reason why the use of pointers is strongly discouraged in FHI-aims. Even when following the textbook, allocating and deallocating pointers works differently with different compilers, opening the possibility of unexpected memory leaks outside our control. Please don’t do it — this problem has bitten us before.

Again, please consult the https://aims-git.rz-berlin.mpg.de wiki for the full and current recommended code conventions.