IRIS EXAMPLE CODE GUIDELINES
Iris code examples are designed to present worked examples of common requests
from the Met Office science community. These are things then that are a little
out of the ordinary and/or a little complex but frequently used within Science.
Worked examples should be in the form of an IPython notebook, which should be
added to this repo and added to the index IPython notebook with a relevant link
title and under a relevant sub-heading (feel free to make a new heading if it
is necessary).
As an Iris developer supplying a new code example then, it is requested that
you observe the following guidelines.
The guidelines, then, are:
1. Describe what is going on. Ideally there should be about as much prose
describing code steps shown as there is code.
2. Use sections. As much as possible, divide the worked example into sections
that encapsulate one element of the example overall.
3. Use pictures as appropriate. As is said, a picture paints a thousand
words. If appropriate then, consider adding a picture to help describe a
particularly complex point. If the worked example generates a plot,
include it!
4. As much as possible, use sample data. Doing so will keep this repo as trim
as possible and means that common data in a known location is being used
as standard.
On occasions where the specifics of the example being demonstrated require
a more targeted dataset, this may be included in the folder called
"sample_data" in the root of this repo. This is not the preferred
approach however, and the total size of added data should be limited as
far as is possible.
5. Code considerations. The code should:
a) be able to run,
b) be Python code, as opposed to iPython notebook code (so not using any
shortcuts available in iPython notebooks), and
c) print versions of any software used, especially for Iris and Cartopy.
6. These should be worked examples, NOT teaching material. As such, the code
supplied should entirely demonstrate the point being made and exercises
for the reader should not be used.