05-style.md

title: Coding Style
teaching: 20
exercises: 10
questions:
- "How should I organise my code?"
- "What are some practical steps I can take to improve the quality and readability of my scripts?"
- "What tools exist to help me follow good coding style?"
objectives:
- "write and adjust code to follow standards of style and organisation."
- "use a linter to check and modify their code to follow PEP8."
- "provide sufficient documentation for their functions and scripts."
keypoints:
- "It is easier to read and maintain scripts and Jupyter notebooks that are well organised."
- "The most commonly-used style guide for Python is detailed in PEP8."
- "Linters such as `flake8` and `black` can help us follow style standards."
- "The rules and standards should be followed within reason, but exceptions can be made according to your best judgement."

plan

• Toby currently scheduled to lead this session
• can base a lot of this on https://merely-useful.github.io/py-rse/py-rse-style.html
• something on project structure and file organization (?)
  • specially relevant if planning to make a python package
  • code organisation & jargon (packages, modules, files, classes, functions)
    • a word about avoiding circular imports (?)
• PEP8
  • pycodestyle/pylint - only warn, doesn't modify code - see also this comparison
  • black - modifies code - note still beta
• documentation
  • docstrings
  • sphinx?
• include tips for good Jupyter hygiene
  • name the notebook before you do anything else!
  • be careful with cell order
  • clear output before saving

{% include links.md %}