Add contributing guide

[znicholls]

Once we're at the point where we know what we're doing re development, it would be good to write a contributing.md document so that others can quickly get going. I'd prefer to not add this into the master branch until it's complete as I always find it very confusing when I get halfway through a document like this and then it suddenly ends/there's gaps. Or we could add it and have a clear warning that it's unfinished.

[znicholls]

@richardcode @chrisroadmap

A few thoughts on some potential rules/guidelines:

• Use test driven development. In very brief it means write your tests first, only write enough code to pass the tests, refactor the code once it's passing so you leave things tidier than when you started, repeat. If you want to read more have a look at this nature article or this intro guide (although even that is fairly long). If you want to read more in detail have a look (here or here.
  • The tests will also act as documentation and ensure consistency.
• Create a style guide
• Avoid code duplication wherever possible. A possible second step for us is to use a code analyser/linter to highlight code duplication where it occurs and run analysis of our code before any merges are executed (i.e. add linting to our continuous integration).
• Take particular care to have the code say what it does clearly. Only resort to comments where you cannot explain why you are doing something any other way.
• Limit methods to a maximum of 10 lines except in exceptional circumstances. Never ever more than 50 lines. Similarly try and have classes be responsible for one thing and one thing only. With this rule in mind, then try to have as few classes as possible.

Most of these thoughts from two books:

• Clean Code by Robert Martin
• Refactoring by Martin Fowler

Right now I don't really care about documentation as the code should be fairly self-documenting if we follow the above. When we do get round to it we should work out how to use sphinx properly but that's a fiddle which is beyond me right now.

[chrisroadmap]

This crosses over with #6 but I've added my thoughts here.

I've added some simple tests in the branch unit_tests. I ran a few minimal examples and saved the output as numpy files. Running pytest performs the calculations and compares them to the saved output, for which an error will be raised if it doesn't agree. These tests are retrospective based on existing code, so this is not TDD, but in future I'll start with this framework when adding in new features. Furthermore the results for the RCP tests will not agree in the future when science changes are implemented.

[znicholls]

Beauty. With practice we'll get better at writing better tests but as long as we're trying we're onthe right path.