Summary: Comments on coding style for developers

Coding Style

Some unobjectionable rules / advice

• Fortran 95 standard constructs only
• Open source code only
• Names are 32 characters max
• Use Doxygen comments, describe well at module, function, and routine level
• I/O should be done through the generalised io module
• MPI should be done through the mpiinterface module
• Only use explicit use statements, no general use statements
• Avoid proliferation of preprocessor directives. If necessary, use a single preprocessor directive in the modules with least dependencies (interfaces) and define a fortran parameter inside
• Passing data through arguments is better
• Avoid copy / paste of similar code, instead generalise and make reusable functions
• Avoid overlong functions
• Create new modules when it is logical, but think about dependencies first !

Way back, we had a discussion about conventions, rules and style in ./doc/devel.tex. Not all aspects of programming style are discussed there. It is not easy or very productive to make an exhaustive list of rules to cover every possibility. However, it is certainly very helpful to keep to a consistent style. It would be nice to do this largely by following the example of existing code. Evolution of style is fine when new constructs are added etc., but unfortunately our individual styles have diverged, so now it is not always what to follow.

Some existing files follow closely the style of revision 1, and additionally have some Doxygen comments, our agreed indents (2) and number of columns (80) etc. Although they do not yet follow all of the recommendations (and perhaps rules in some cases), they do provide something to follow with regards to comments, use of whitespace etc. Therefore, it is suggested that we follow these by example.

To date these files are matdat.F90, non_linear_terms.F90, switches.F90 and index_function.f90.

(We should check if there are inconsistencies between the styles of those files and add more files to this list as appropriate)

Repository Etiquette

• Always run the test cases before pushing to develop or master.
• Check-ins related to existing issues should refer to that issue.
• Checks-ins should not attempt to fix many different issues at once. Cosmetic reformatting should also be done in dedicated check-ins.
• Branches are allowed for encouraged for any major development but should be merged into develop as soon as possible.