9 Python Style Guide
PEP 8, and Google have python style guides which we generally try to follow, though we have made some different choices in some respect.
9.1 The conventions we use
First off we try to be compliant to the https://www.python.org/dev/peps/pep-0008/
the summary is as follows:
- Use 4 spaces, not tabs (you can get your editor to do this automatically, and it is recommended for coding in general).
- If your function has many inputs, list them vertically by having an extra indent or more
- We use CapitalizedWords and MixedCase mostly in our code. We capitalize the first letter to signal that this is a class, and we keep it in lowercase if it is an instance of a class, or a function. This allows us to easily see what we´re working with.
- We disobey the convention on function names, where PEP 8 wants them to be lowercase and separated by underscores, we use mixedCase for functions as well. This is due to underscore being a hassle to use.
- If you have a list of things, add list to the name. Do not use plurals. good: vesselList, bad: vessels
- Further, as we have a project with a lot of functional files, we often use "import .... as" method, where we have a list of abbreviations that are convenient to follow
- Have clear names and use proper namespacing in your code
- Document your code with docstrings adhering to the Goodle docstring standard. Clearly indicate what is input and what is outout. Especially side-effects!
- Structure your code so that it is as self-explanatory as possible, and use comments where additional clarification is useful.
- Remember that all code you write will end up being treated as a "black box" sooner or later. So make sure that it actually works like one, with clean input-output dichotomy.
- Exceptions should crash your program, unless you have very specific reasons why it should not.
- If you absolutely want to stop exceptions, you should not use "except", as this will catch the system exit and keyboard interrupts. If you want catch-all use "except Exception as e"
- You should catch, append and re-raise the exception at each level of the code, so that an informative traceback will appear when the program dies.
- Unit Testing is desirable, and you should test the crucial behavior of each feature you wish to push to the main project. Also, test that the code fails the way it should. Few things are as hard to track down as code that passes wrong data onto other parts in the program
- Keep your Unit tests. Write them well. Systematize them. Make sure they´re thorough, independent of each other, and fast.
9.3 The code is the documentation... i.e. the docs always lie!
Write the code as clearly as possible to what it is doing. Clear, succinct variable names and conventions, and ideally code review.
9.4 Docstring Guide
The google docstring guide is located at Google Style Python Docstrings