Working Practices

This document and the working practices are constantly evolving to meet changing requirements and as we learn new things. We are happy to receive suggestions for improvements in the form of a pull request (PR) or by email to miao@metoffice.gov.uk. For more substantial suggested changes, opening an issue may be the best way to present a change for consideration.

• General considerations for new work
  • Which repository does this code belong to?
  • Where should code be added?
  • Is the planned development going to be in python?
  • Does the change mean a change in the dependencies required in ANTS environments?
• Principles
  • Readability
  • Robustness
  • Ease of use
• Developer guide
  • Development process
    • Creating an issue
    • Forking the repository
    • Creating a branch
    • Making changes
    • Opening a pull request
    • Working with your reviewer during the code review process
  • Code conventions
    • Standard tools
    • Modular code
    • Deprecated code
    • Whitespace
    • Full names for variables, objects, functions, etc
    • Assert
    • Identifying coordinates on a cube
    • Line lengths
    • Filtering objects
    • Warnings
    • TODO, FIXME, etc
    • Workarounds
    • Custom exceptions
    • Use pure functions and avoid in place operations
    • Strict Zip
    • Automated coding standards tools
    • Jupyter notebooks
    • Binary files
  • Licensing and attribution
    • Licence, copyright, and IPR
    • AI assistance and attribution
  • Testing
    • Why do the ANTS/UG-ANTS team ask for unit tests and rose stem tests for code?
    • Unit test conventions
      • What needs to be unit tested?
      • What does not need to be unit tested?
      • Test names
      • Docstrings
      • Readability
      • Test style
      • assertRaises and assertRaisesRegex
      • assertIsNone and assertIsNotNone
      • Mock conventions in tests
      • Running unit tests in a working copy
      • Advice on unit tests
    • Rose stem test conventions
      • What needs to be tested via rose stem?
      • Decomposition splits in KGO tests
      • Source data files
      • Output filenames in KGO tests
      • Linkcheck test
      • Rose configuration
      • Long form command line arguments
      • Running rose stem tests
  • Documentation
    • Sphinx details
    • Sphinx codeblocks
  • Application considerations
    • Shell scripts
    • “Run once” scripts
  • Developer environments
• Reviewer guide
  • Prerequisites
  • Reviewer considerations
  • Review comments