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.

Virtualenvs/Virtualenv-wrapper

Introduce yourself to virtualenv-wrapper, learn the basic handling.

• https://virtualenvwrapper.readthedocs.io/en/latest/
• (for reference https://virtualenv.pypa.io/en/stable/)

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

Git Literature

• https://try.github.io/levels/1/challenges/1
• http://git-scm.com/book
• http://www.ralfebert.de/tutorials/git/
• http://www-cs-students.stanford.edu/~blynn/gitmagic/

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.53
  

• Use 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:

• http://git-annex.branchable.com/

• 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

• http://sphinx-doc.org/tutorial.html

• 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