ESCOMP / ESCOMP/CTSM

Document important stylistic conventions on the wiki

Open
#835 6 comments 0 reactions 0 assignees View on GitHub
docs-loc:other docs:new documentation priority: low
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.