Coding guidelines

We add some notes here to get a consistent coding experience :)

Comments

  • should be usable for pydoc
    • ''' or """ at the beginning of every class/method
    • use ## for longterm comments, that are useful for understanding
    • use #blabla for lines of code, that are disabled for experimenting and might be used later again
  • add TODO and FIXME where appropriate

Indentation

  • use tabulators for indentation

Error handling

  • unspecific exception catching is evil - try: grep -r except: .
  • catch all possible errors and write details to the log facility: self.cbox.log.error("Failed to ...")

Unittests

  • first write a unittest and then write the relating code until the unittest stops failing :)
  • src/cryptobox/tests/unittests.modulename.py should contain tests for modulename.py
  • test classes requiring a webserver must inherit WebInterfaceTestClass from cryptobox.tests.base
  • commits with broken unittests are evil: fix or disable the code - not the test ;)

Code improving

We have some tools to ensure nice working code.

Unittests

  • run bin/do_unittests.sh
  • motivation: green bar

TODOs

  • run scripts/show_TODO.sh
    • try to fix some TODOs
    • open a ticket for bigger workload
  • motivation: keep the sources clean of TODOs

Cheesecake