Developer Guide

Overview

• Coding requirements
• Testing requirements
• Documentation requirements
• Cylc best practice
• Rose requirements

Coding requirements

• All files must start with the following two comments, where <year> is either <year_of_first_publication> or <year_of_first_publication>-<year_of_last_modification>:

  # (C) Crown Copyright <year>, Met Office.
  # Please see LICENSE.md for license details.
  

• Use f-strings

Testing requirements

Python tests

• Python test modules must be located in the app/unittest/tests/ directory, in a parallel directory structure to the Python modules they are testing, e.g. tests for the app/configure_standardise/bin/create_variables_file.py module must be located in the app/unittest/tests/test_configure_standardise/test_create_variables_file.py test module
• Test function names must have the form test_<name_of_thing_being_tested>_<additional_description>, where <additional_description> uses full words to describe the specific feature of <name_of_thing_being_tested>
• Test functions should typically test one thing (often this means one assert statement, but not always) and follow the pattern:

  def test_my_function_for_reason():
      actual = my_function(arg1, arg2, ...)
      expected = <expected_output>
      assert actual == expected
  

• Use np.testing.assert_allclose when comparing arrays / array-like objects
• Test functions should not have docstrings (the tests are excluded from the Sphinx documentation build); instead, use comments to document the tests

Documentation requirements

General documentation

• Capitalised acronyms should be used when using acronyms
• Limit all lines in markdown (.md) files and .rst files to a maximum of 79 characters

Python documentation

• Use the ​NumPy Docstring Standard when writing docstrings
• All parameters must be described in the docstrings, including their types
• All docstrings must contain a summary line that starts with Return <description>., see the 4th point in the Notes section in PEP 257: Docstring Conventions
• The line lengths of all docstrings and comments should be limited to 72 characters, see PEP 8: Style Guide for Python Code
• All sentences in docstrings and comments must start with an upper case letter, end in a period and use the correct grammar; all words must be spelt correctly

Cylc best practice

• The Cylc: Workflow Design Guide must be followed to ensure CMEW is clear, maintainable, and portable.

Rose requirements

• When using Rose's File Creation Mode, do not use braces around any environmental variables used. For example, use [file:$MY_ENV_VAR] rather than [file:${MY_ENV_VAR}], see issue #201 for more details.
• Use the following flow diagram to determine where an environment variable should be defined:

---
title: Where should my environment variable be defined?
---
flowchart TB
    question_multiple1{"
      Is the environmental
      variable used by multiple
      tasks?
    "}
    question_multiple2{"
      Is the environmental
      variable used by multiple
      tasks?
    "}
    question_override{"
      Should it be possible to
      override the environmental
      variable, either by the user
      or for testing purposes?
    "}
    output_global_override["
      Define the environmental
      variable in the 
      'rose-suite.conf' file
    "]
    output_app_override["
      Define the environmental
      variable in the 'env' 
      section in the 
      'rose-app.conf' file
    "]
    output_global["
      Define the environmental
      variable in the
      'root:environment' section
      in the 'flow.cylc' file
    "]
    output_app["
      Define the environmental
      variable in the 
      '(taskname):environment'
      section in the 
      'flow.cylc' file
    "]
    question_override --Yes--> question_multiple1 --Yes--> output_global_override
    question_multiple1 --No--> output_app_override
    question_override --No--> question_multiple2 --Yes--> output_global
    question_multiple2 --No--> output_app

Loading