Introduction
This page defines guidelines and best practice when developing Python components for the SCAPE project. It has been defined as part of the initial functional review (MS17), however these guidelines are open for discussion, amendment and adaptation as appropriate.
Python
The following section provides guidelines for developing software using Python.
Coding Standards
The PEP8 - Style Guide for Python Code
SHOULD be used.
Comments
Please use them.
DocStrings
As highlighted in PEP8, docstrings MUST be written for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public methods, but you should have a comment that describes what the method does.
PEP257 - DocString Conventions SHOULD be used for writing good docstrings.
Unit Tests
Up-to-date unit tests MUST accompany ALL non-trivial code.
If in doubt about the triviality of a method, save time wondering and write a test any way. If you're finding it hard to design or write a test for a particular piece of functionality, it probably means you don't fully understand what you're about to try to implement.
Unit Tests are good because:
- They help reduced bugs in new and existing features.
- Help improve design and facilitate re-factoring.
- Provide working examples for other programmers, and supporting documentation (though you remembered the JavaDoc, right?).
- Help those who may have to work on the code in the future.