Coding Conventions

The uwtools development team have adopted certain coding conventions and has tried to uphold them throughout the code base. Expect that reviews may touch on any of these topics.

• Error handling: The code should raise exceptions, specifically those defined in uwtools.exceptions, when the user has made a mistake that they might be able to correct, but should fail assertions when the developer has made a mistake that users cannot correct. Additional exceptions may be defined in module uwtools.exceptions as needed.

• Naming tests: The individual tests in the tests/ modules should be named by the module or class being tested, followed by an underscore and the method or function. Private methods or functions, as denoted by a leading underscore, will therefore require a double underscore in the name. For example, module foo contains functions bar and _baz, the tests’ names would be test_foo_bar and test_foo__baz. When multiple tests target the same method or function, append a short descriptive suffix separated by two underscores to distinguish the behavior being tested, i.e., test_foo_bar__pass and test_foo_bar__fail.

• Ordering: In the absence of a more natural way of ordering a list of items, including function arguments, lexicographical ordering should be used. When not using lexicographical ordering, comment(s) describing the ordering are appreciated.

• Pull requests: When opening a PR that significantly changes the code base, the contributor should be the first to formally review the code while the PR is still a draft, adding helpful comments that will walk other reviewers through the changes. Specifically, add line-level comments in the PR (or file-level, where applicable) to explain non-obvious decisions, important context, or areas that deserve closer attention. Waiting until after the initial contributor review is submitted to mark the PR “Ready for Review” reduces the number of emails sent to the reviewers.