Document important stylistic conventions on the wiki
- Dominant language
- Fortran
- Stars
- 352
- Forks
- 361
- Avg merge
- 2d 21h
- Merged PRs (30d)
- 7
Description
We should document our most important stylistic conventions on the wiki. We have a placeholder (https://github.com/ESCOMP/CTSM/wiki/CTSM-coding-guidelines), which points to the old page https://wiki.ucar.edu/display/ccsm/CLM+Coding+Conventions . Some of that could be kept (moved into the github wiki, though), but some of that isn't as relevant / important, we should add some other things, too.
Some important points that should be called out:
- Module, subroutines and functions should be written using the standard header style (give an example of what this looks like).
- Subroutine calls with more than a few arguments should use keyword-value; this is especially important when arguments are built-in types rather than derived types, to avoid incorrect ordering of arguments.
- Variables should have self-describing names, without being too long
- Subroutine arguments and local variables should appear one per line. Most variables should have a comment documenting the variable and (importantly) the units. An exception is simple loop counters, which can be combined in one declaration (e.g., `integer :: fc, c, p, g`)
- Avoid whole-array assignments for things indexed by gridcell, landunit, column, patch
- Definitely avoid (:) - at least use bounds
- Ideally avoid doing something for all points within bounds, too: ideally use filters
- Associates: keep basic name (for the sake of searchability) (e.g., `some_variable => container%some_variable_col`)
- Passing arrays: use (:) with a `SHR_ASSERT_FL` to assert expected size call (give example)
- Indentation
- New conventions agreed upon yesterday for naming:
- Module and file names (note that file name should mimic the module name): `PascalCase`. No need for `Mod` at the end (either for modules that have science without a derived type, or modules that have both a derived type and science), but if a file just contains a dumb type (with just infrastructure - no real science), can end it in `Type`. (Note: we may or may not go back and rename existing modules to remove the `Mod` at the end.)
- Everything else (subroutines, functions, type names, variable names and constants): `lowercase_with_underscores`
We could possibly point to a module that illustrates many of these points well.
Contributor guide
Assessment
This issue has not been assessed yet.