Repositories¶
For internal projects, use out Gitlab-server: https://gitlab.geo.uni-bonn.de:4443/users/sign_in
Python requirements¶
- We use Python 3.X for development.
Git requirements¶
Understand, and use, the following git commands:
- git clone
- git pull / git push
- git add
- git commit
- git branch
- git checkout
- git merge
Software Development using Python¶
Use setuptools to create an installation routine (https://setuptools.readthedocs.io/en/latest/setuptools.html)
Python Koans: https://github.com/gregmalcolm/python_koans
Never, ever, overwrite data in variables:
data = np.random.rand(10) # DO NOT # data = data + 1.53 # instead create a new variable data_w_offset = data + 1.53Use GIT for all software projects, even small ones!
Generated data usually does NOT belong into git repositories.
- Put scripts to generate the data into the GIT rep.
- git-annex can be used to manage large data files in git-repositories:
- Use Python 3.4 or newer
- Make use of the ipython notebook (http://ipython.org/documentation.html)
- Follow the PEP8 style guide (http://www.python.org/dev/peps/pep-0008/)
- The program ‘pep8’ checks .py files for pep8-errors (apt-get install pep8)
- Use 4 spaces instead of TAB (can be set in most editors, otherwise: use another editor)
- maximum 79 characters per line
- Each executable script should start with “!#/usr/bin/python”
- make executable with “chmod +x SCRIPT.py”
- execute with ./SCRIPT.py
- Bookmark the documentations for the following packages (local version can often be found in /usr/share/doc/python-XXX)
- Python (http://docs.python.org/2/)
- IPython (http://ipython.org/documentation.html)
- Matplotlib (http://matplotlib.org/contents.html)
- Numpy (http://docs.scipy.org/doc/)
- Scipy (http://docs.scipy.org/doc/)
- Pandas (http://pandas.pydata.org/pandas-docs/stable/)
- Nosetests (https://nose.readthedocs.org/en/latest/)
- Decide on the project language in the beginning and stick to it!
- English is the preferred language to comment and document your software
- Create working examples for your software in a ‘examples/’ subdirectory.
- These examples are directed to new users who want to learn how to use the software in general or how to use specific features.
- Create working test cases for your software in a ‘tests/’ subdirectory.
- Tests should cover most of the features (large and small)
- Tests can be automated using ‘nosetests’ https://nose.readthedocs.org/en/latest/
- Create a documentation subdirectory ‘docs’ right at the beginning
- Use ‘sphinx’ (http://sphinx-doc.org/) for the documentation
- Document all functions
- Documentating early and extensive has multiple advantages
- Re-use text for publications/thesis
- Structure the development phase
- A central place to store notes and todos
- sections to include in your documentation:
- Installation
- Quick start guide
- Usage
- Implemented formulas
- TODO-List
- Literature (include links to PDF files if available), put PDF files in a directoy ‘literature’
- Design-sketches (flow-charts)
- Code (can be automatically included by sphinx)
- A ‘docs’ subdirectory could have the following subdirectories:
- literature/ <- put PDF files in here
- doc/ <- put sphinxs documentation in here
- <- add new subdirectories for all notes and additional documentation
- Create only small functions (~1 screen page long) with only one purpose
- NEVER ever start your variables with “my”!
- Plan your program on paper before you start to write code
- Use pseudocode
- Flow-charts really help to understand the problem
- If possible give the code to a colleage in regular intervals for a code review
- See http://infinitemonkeycorps.net/docs/pph/ for a whole tutorial on Python project management