# Best Pracices for writing reliable, readable and maintainable code

Go into the breakout rooms and **collect best practices to write reliable, readable and maintainable scientific code.** Use the following papers and the PEP8 style guide as sources:

1. Wilson, G., Aruliah, D. A., Brown, C. T., Hong, N. P. C., Davis, M., Guy, R. T., ... & Waugh, B. (2014). [Best practices for scientific computing](https://journals.plos.org/plosbiology/article?id=10.1371/journal.pbio.1001745). PLoS biology, 12(1).
2. [PEP8: Style Guide](https://www.python.org/dev/peps/pep-0008)
3. Wilson, G., Bryan, J., Cranston, K., Kitzes, J., Nederbragt, L., & Teal, T. K. (2017). [Good enough practices in scientific computing](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1005510). PLoS computational biology, 13(6).

Give a short heading (e.g like in the paper) and if time permits add a short description (1-2 sentence) or example(s).

## Readability (Breakout Room 1)
- write programs for people, not computers
* A program should not require its readers to hold more than a handful of facts in memory at once.
* programs should limit the total number of items to be remembered to accomplish a task
* break programs up into easily understood functions
* Make names consistent, distinctive, and meaningful.
* Make code style and formatting consistent.
- Don't repeat yourself (or others)
* every piece of data must have a single authoritative representation in the system
* every geographic location from which data has been collected should be given an ID
* modularize code rather than copying and pasting
* modularizing code allows people to remember its functionality as a single mental chunk
* Re-use code instead of rewriting it
* using established libraries and packages

- PEP8
- Code Lay-out
- Indentation, spaces instead of tabs (consistent), maximum line length, blank lines, imports, comments,
- Naming Conventions

- Zen of Python
- import this
- print(''.join(this.d.get(el, el) for el in this.s))
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

## (Example) Explicit is better than implicit (2. line Zen of Python)

lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]])

### (Example) Make names consistent, distinctive, and meaningful.

Don't use:

XYZControllerForEfficientHandlingOfStrings = 12
XYZControllerForEfficientStorageOfStrings = 12

Polygonize_Vector_ABC_abc = ...

## Maintainability (Breakout Room 1)
- Make the computer repeat tasks
* Use functions for repeating code --> changes/fixes to be implemented once instead of multiple times
* Modularize code rather than copying and pasting.

- Make incremental changes.
- Work in small steps with frequent feedback and course correction.
- Use a version control system.
* takes parts of an existing code and stores these parts as copies in a repository
* This makes it easier to modify and admit comments on the code by programmers
- Put everything that has been created manually in version control.
- Document design and purpose, not mechanics.
- Collaborate
- Use an issue tracking tool.
- Always search for well-maintained software libraries that do what you need
* Test libraries before relying on them

## Reliability (Breakout Room 2)

- Style Guide:
- Unittest: check all possible inputs and check for right behaviour
- Exception Handling: use named exceptions
- Variable / Type Annotations
- unique variable, class, function names (prevent override build in methods/types)
- same return convention in functions
- assertions to prevent pointless input, check if everything is still fine
-

- Plan for mistakes
- Add assertions to programs to check their operation.
- Use an off-the-shelf unit testing library.
- Turn bugs into test cases.
- Use a symbolic debugger.