Code quality guide

What good code looks like in this project. This guide covers judgement calls. Commands, the architecture and the safety invariants are in CLAUDE.md, and they win if the two ever disagree. Protecting someone’s photos comes before tidiness, so a rule here never justifies weakening a safety check.

Before you open a PR

Clean code

DRY and reuse

Leave it better than you found it

Maintainability

Errors

Helpful logging

Most of this runs unattended under launchd, so the logs are often the only witness.

Ease of use

What’s enforced

CI runs these, so don’t spend review time on them:

Check Catches
ruff check . Lint errors, import order, complexity over 15
ruff format --check . Code that isn’t formatted; run ruff format . to fix it
unittest discover Regressions, on Python 3.9, 3.11, 3.13 and 3.14
bash -n Shell syntax errors
compileall / py_compile Python that doesn’t compile, including bin/

Everything else in this guide is for the author and the reviewer. If a rule keeps getting missed and a tool could catch it, add the tool.

Known gaps

Where the code doesn’t meet this guide yet, measured on 2026-11-05. Improve these when you’re working nearby. They aren’t a reason to copy the pattern.