Application considerations
==========================

Processing should be split into separate applications for model-independent
preprocessing, and model-dependent processing.

In many **existing** applications, the convention was that
``main`` and ``load_data`` functions did not need docstrings.  The intent was
that the application contained minimal code, so docstrings and unit testing were
not needed.  In practice, more code has ended up in applications than
anticipated, so for **new** applications docstrings and unit tests should be
included, and for **updates** to existing applications, docstrings and unit
tests should be considered on a case by case basis.

In ANTS and ancillary-file-science applications, the ``main()`` function should return
the cubes generated by the application, as well as saving them to disk.

In UG-ANTS and ug-ancillary-file-science applications, the ``run()`` method of the
application class should not return anything, but should assign data to be saved to the
``self.results`` attribute. Saving is then carried out by calling the ``save()``
method.

Applications should be made executable with:

.. code-block:: bash

    chmod +x <application>

and should start with a shebang::

    #!/usr/bin/env python

Applications should work on current hardware up to at least n1280e (UM) or C896
(LFRic) resolutions.

.. _shell-scripts:

Shell scripts
-------------

Bash shell scripts may be needed in some cases (although Python is preferred in
most cases). If these are needed:

1. Use ``set -eu`` to cause errors for undefined variables and to fail on first
   error.  ``set -x`` to echo all commands prior to running may also be useful
   while debugging.
2. Run ``shellcheck`` on the script to identify common pitfalls.

.. _run-once-scripts:

"Run once" scripts
------------------

Some scripts for fixing source data are run once, with the results centrally
lodged (e.g. generating master files).  These scripts do not need to
be kept up to date with changing ANTS environments and can be allowed to get
stale.  Similarly, there is a little more flexibility around code conventions
and testing for these scripts.

"Run once" scripts should only be stored in the `ancillary-file-data-preparation
<https://github.com/MetOffice/ancillary-file-data-preparation>`_ repository.