Newer
Older
---
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 (?)
- `pycodestyle`/`pylint` - only warn, doesn't modify code - [see also this comparison](https://books.agiliq.com/projects/essential-python-tools/en/latest/linters.html)
- `black` - modifies code - note still [**beta**](https://github.com/psf/black#note-this-is-a-beta-product)
- 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 %}