Main Criteria

• readable/understandable
  • others can easily understand
  • also in the future you will know what the code does
  • no need for explanations when shared with other
  • self-contained
• reusable
  • can be applied to variety of situations
  • no need to rewrite everything, recycle existing code
• testable
  • easy to debug

Code Planning

Questions to Ask

• what shall my code do
• what are the steps to get there
• how do I complete each step
  • input, methods, output

Pseudocode

description of an algorithm in a mixture of plain english and programming language conventions

• easy to understand
• language independent
• focus on fundamental logic without worrying about syntax
• should (in principle) compile without errors

#pseudocode for gradient decent
choose x_0, learning rate: tau
for all k >= 0 do
    x_(k+1) = x_k - tau * gradient(f(x_k))
end for           

Flowcharting

• graphical alternative to pseudocode
• start simple, get more elaborate (function inputs, memory allocations, ...)
• tools
  • pen and paper
  • Mermaid
• for the pseudocode example:

flowchart LR
    start@{ shape: start, label: "Start"}
    init@{ shape: rect, label: "init parameters"}
    increment@{ shape: rect, label: "proceed to next iteration"}
    grad@{ shape: process, label: "compute gradient"}
    update@{ shape: process, label: "update parameters using gradient"}
    check@{ shape: decision, label: "maximum number of iterations reached?"}
    output@{ shape: in-out, label: "output optimal solution"}
    stop@{ shape: stop, label: "End"}

    start --> init
    init --> increment
    increment --> grad 
    grad --> update
    update --> check
    check -->|yes| output
    output --> stop
    check -->|no| increment

Naming Conventions

• camelCase, PascalCase, snake_case, SCREAMING_SNAKE_CASE

try to follow the community of the language you're using

• examples from PEP 8
  • modules: short, snake_case
  • classes: PascalCase
  • methods: snake_case
  • functions: snake_case
  • variables: snake_case
  • constants: SCREAMING_SNAKE_CASE
• tabular data
  • find your own style (I use <quantity>_<context>_<source>[_e] [<[unit]>])

Refractoring

• break big chunks into functions and classes
  • add comments and docstrings
  • checkout this repo for a template
• catalog sets of function with similar context into importable modules
  • checkout this repo for an example
  • logging for insight and debugging

Testing

• remember session2_01_python?
  • cn5_test.py was the example we had

3-Step Process

1. make it work
   • ensure correct outputs and behavior
2. make it right
   • make readable
   • make maintainable
   • figure out correct structure
3. make it fast
   • optimize performance

Conquer the Commandline

• powerful for code that is executed often
• uv allows easy creation of commandline tools

use a separate uv project for each commandline tool

• can also be done using python

python <yoursript.py> [args]

• use argparse for variability
  • see commandlinetool/ for an example

#run from project root
python3 content/session3_01_good_practises/commandlinetool/src/commandlinetool/main.py 1 -o "optarg"

• uv allows easy creation of commandline tools

use a separate uv project for each commandline tool