BSN Coding Standards

1 Allgemeine Prinzipien

2 Code-Stil (PEP 8+)

Durchsetzung: ruff check + ruff format AUTO

2.1 Zeilenlänge

Maximal 100 Zeichen. 88 (Black-Default) ist zu knapp für Flask-Routen und SQLAlchemy-Queries.

2.2 Einrückung

• 4 Leerzeichen pro Ebene — NIE Tabs
• Fortsetzungszeilen: doppelte Einrückung (8) oder vertikale Ausrichtung

# ✅ Richtig — vertikale Ausrichtung
result = some_function(
    argument_one,
    argument_two,
    argument_three,
)

# ✅ Richtig — doppelte Einrückung bei Bedingungen
if (some_very_long_condition
        and another_long_condition):
    do_something()

2.3 Quotes

• Doppelte Quotes (") für Strings
• Einfache nur, wenn der String " enthält
• Docstrings: immer """triple double"""

def get_games() -> list[dict[str, object]]:
    """Holt alle Spiele aus der Datenbank."""
    ...

2.4 Imports

Reihenfolge (automatisch): 1. Standard-Library 2. Drittanbieter 3. Projekt-intern

2.5 Trailing Commas

Immer bei mehrzeiligen Collections.

items = ["Brettspiel", "Kartenspiel", "Würfelspiel",]

3 Typ-Annotationen

Durchsetzung: mypy --strict AUTO

# ✅ Richtig — X | None (PEP 604, idiomatisch für 3.13+)
def get_game_by_id(game_id: int) -> dict[str, str | int] | None:
    """Holt ein Spiel anhand seiner ID."""
    ...

# ❌ Falsch — keine Typen
def get_game_by_id(game_id):
    ...

3.1 Spezifische Typ-Regeln

4 Namenskonventionen

Zusätzlich

• Boolesche: is_active, has_permission, should_retry
• Funktionen als Verben: get_, create_, validate_
• Keine Ein-Buchstaben-Variablen (außer Comprehensions)
• Keine kryptischen Abkürzungen

5 Kommentare & Docstrings

Google-Style Docstrings

def berechne_durchschnitt(werte: list[float]) -> float:
    """Berechnet den arithmetischen Durchschnitt.

    Args:
        werte: Liste von Gleitkommazahlen.

    Returns:
        Der Durchschnittswert.

    Raises:
        ValueError: Wenn die Liste leer ist.
    """
    if not werte:
        raise ValueError("Die Werteliste darf nicht leer sein.")
    return sum(werte) / len(werte)

6 Projektstruktur & Architektur

6.1 Maximalgrößen

6.2 Verzeichnisstruktur

project/
├── app.py              # Flask-App-Factory + Config
├── routes/             # NUR Request-Handling — keine Business-Logik
├── services/           # Business-Logik (Validierung, Berechnung, DB)
├── models/             # DB-Modelle — nur Schema, keine Logik
├── utils/              # Pure Functions — kein Zustand, keine DB
├── templates/          # Jinja2 — CSS IMMER inline
├── static/             # JS, Bilder
├── tests/              # Spiegelt src/-Struktur
├── migrations/         # Alembic
├── pyproject.toml      # ALLE Konfiguration an einem Ort
├── .pre-commit-config.yaml
└── CODING_STANDARDS.md

6.3 Architekturprinzipien

7 Sicherheit

Durchsetzung: ruff (S-Regeln = flake8-bandit) AUTO

7.1 Secrets

7.2 Input-Validierung

• Alle User-Inputs validieren vor Verarbeitung
• SQL-Injection: Parameterisierte Queries (SQLAlchemy Default)
• XSS: User-Input escapen (Jinja2 Default)

7.3 Weitere Regeln

• Keine assert-Statements in Produktionscode AUTO
• Kein pickle für ungetrustete Daten
• subprocess mit shell=False (Default)
• Passwörter: bcrypt oder argon2 — nie md5/sha1
• HTTPS überall — HSTS-Header setzen

8 Testing

Durchsetzung: pytest --cov --cov-fail-under=80 CI (nicht in pre-commit)

8.1 Grundregeln

1. 80% Code Coverage als harter Floor — unterschreiten blockiert den Merge in CI
2. Empfohlen: TDD (Test-Driven Development) — erst Test, dann Code
3. pytest als einziges Test-Framework
4. Tests in tests/, Struktur spiegelt src/

8.2 Test-Beispiel

class TestGameService:
    def test_get_by_id_returns_game_when_found(self, db_session):
        # Arrange
        service = GameService(db_session)
        # Act
        result = service.get_by_id(1)
        # Assert
        assert result is not None
        assert result.name == "Catan"

9 Flask-spezifische Regeln

# ✅ Route — korrekte Typen, methods explizit
@app.route("/api/search", methods=["GET"])
def search_games() -> tuple[dict[str, object], int]:
    query = request.args.get("q", "").strip()
    if not query or len(query) > 100:
        return {"error": "Ungültiger Suchbegriff"}, 400
    return game_service.search(query), 200

Config & UI

• app.config.from_prefixed_env() — Secrets nie hartkodieren
• CSS immer inline in Templates
• Mobile-first, Primärfarbe BSN-Blau #20228a
• Touch-Buttons min 64px, Overlays min 85vh

10 Git & Commits

Conventional Commits

<type>(<scope>): <description>

Commit-Hygiene

• Nach jeder abgeschlossenen Aufgabe committen
• Ein Commit = eine logische Änderung
• Vor jedem Commit: pre-commit run + pytest

11 Toolchain & Automatische Durchsetzung

11.1 Täglicher Workflow

# 1. Einmalig: Tools installieren
pip install ruff mypy pre-commit pytest

# 2. Einmalig: Hooks aktivieren
pre-commit install

# 3. Beim Coden: Formatieren + Linten (auto-fix!)
ruff check . --fix
ruff format .

# 4. Typ-Prüfung (im Projekt-venv, NICHT in pre-commit)
mypy .

# 5. Tests ausführen
pytest --cov --cov-fail-under=80

# 6. Commit — pre-commit prüft AUTOMATISCH
git commit -m "feat: neue Spiele-Suche"
# → Ruff Lint + Format laufen automatisch
# → Basic Checks (Merge-Konflikte, Whitespace, Debug-Statements)

11.2 Was wird automatisch geprüft?

11.3 Was wird NICHT automatisch geprüft?

Diese Checks sind manuell im Review durchzuführen oder laufen in CI:

• mypy — läuft lokal + in CI gegen das echte venv (siehe Fix #5)
• Dateigrößen-Limits (500 Zeilen/Modul, 300 Zeilen/Klasse) — manuelles Review
• Coverage 80% — pytest --cov muss manuell ausgeführt werden (oder in CI)

11.4 CI-Setup (später)

# .gitea/workflows/quality.yml (Gitea Actions — GitHub-kompatibel)
- name: Lint + Security
  run: ruff check .
- name: Type Check (im echten venv!)
  run: mypy .
- name: Tests + Coverage
  run: pytest --cov --cov-fail-under=80

12 Code-Review-Checkliste

Bei jedem Code-Review durchgehen. AUTO = wird von pre-commit erzwungen.

• AUTO PEP 8 eingehalten? (Ruff-Check bestanden)
• AUTO Keine from module import *?
• AUTO Keine Debug-Statements (pdb, breakpoint)?
• AUTO Keine Merge-Konflikte im Code?
• Alle Funktionen haben vollständige Typ-Annotationen? (mypy bestanden)
• Docstrings auf Deutsch für alle öffentlichen Funktionen?
• Keine Secrets im Code?
• User-Input wird validiert?
• Tests geschrieben und grün? Coverage ≥ 80%?
• Keine God-Files (>500 Zeilen)? MANUELL
• Funktionen max 50 Statements, McCabe ≤ 10? AUTO
• Route enthält keine Business-Logik?
• Commit folgt Conventional Commits?
• Keine zirkulären Imports?

13 Konfigurationsdateien (Referenz)

Diese Dateien werden im Projekt-Root abgelegt. Alle Review-Fixes sind eingearbeitet.

13.1 pyproject.toml

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "bsn-community"
version = "0.1.0"
description = "Brettspiel-News Community-Projekt"
requires-python = ">=3.13"
readme = "README.md"
license = {text = "Proprietary"}
authors = [{name = "Daniel Krause", email = "info@brettspiel-news.de"}]

# ── Ruff: Linting + Formatierung + Sicherheit ──
[tool.ruff]
line-length = 100
indent-width = 4
target-version = "py313"

[tool.ruff.lint]
select = [
    "E",     # pycodestyle errors
    "F",     # Pyflakes
    "W",     # pycodestyle warnings
    "I",     # isort (Import-Ordnung)
    "N",     # pep8-naming (Namenskonventionen)
    "UP",    # pyupgrade (auto-upgrade auf 3.13-Syntax)
    "B",     # flake8-bugbear (Common Bugs)
    "C4",    # flake8-comprehensions
    "SIM",   # flake8-simplify
    "TCH",   # flake8-type-checking
    "RUF",   # Ruff-spezifische Regeln
    "S",     # flake8-bandit — Sicherheit (ersetzt separaten Bandit-Hook!)
    "D",     # pydocstyle (Docstrings)
    "C90",   # McCabe-Komplexität
    "PL",    # Pylint-Regeln (too-many-*)
]
ignore = [
    "D100",  # Modul-Docstring optional
    "D104",  # Package-Docstring optional
    "D107",  # __init__ Docstring optional
    "D203",  # Konflikt mit D211
    "D213",  # Konflikt mit D212
]
fixable = ["ALL"]

[tool.ruff.lint.mccabe]
max-complexity = 10

[tool.ruff.lint.pylint]
max-statements = 50    # PLR0915 — entspricht „max 50 Statements/Funktion"
max-args = 7           # PLR0913
max-branches = 15      # PLR0912

[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = ["S101", "D103"]   # asserts + fehlende Docstrings in Tests erlaubt
"migrations/**/*.py" = ["D"]         # Keine Docstring-Pflicht in Migrationen

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
line-ending = "auto"

# ── mypy: Statische Typ-Prüfung ──
[tool.mypy]
strict = true
python_version = "3.13"
exclude = ["migrations/", "tests/"]
warn_unreachable = true
warn_unused_ignores = true
enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]

# ── pytest: Testing ──
[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = "test_*.py"
python_classes = "Test*"
python_functions = "test_*"
addopts = [
    "--strict-markers",
    "--tb=short",
    "--cov=src",
    "--cov-report=term-missing",
]
markers = [
    "slow: Langsame Tests (Datenbank, API-Calls)",
    "integration: Integrationstests",
]

13.2 .pre-commit-config.yaml

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.15.18
    hooks:
      - id: ruff
        name: "🔍 Ruff — Linting + Sicherheit"
        args: [--fix]
      - id: ruff-format
        name: "🎨 Ruff — Formatierung"

  # mypy läuft NICHT in pre-commit (isoliertes venv-Drift-Problem).
  # Stattdessen: manuell mit `mypy .` oder in CI gegen das echte venv.

  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: check-added-large-files
        name: "📦 Keine großen Dateien (>5 MB)"
        args: [--maxkb=5000]
      - id: check-merge-conflict
        name: "⚠️ Keine Merge-Konflikte"
      - id: trailing-whitespace
        name: "🧹 Kein Whitespace am Zeilenende"
      - id: end-of-file-fixer
        name: "📄 Dateien enden mit Newline"
      - id: check-yaml
        name: "📋 YAML-Syntax prüfen"
      - id: check-toml
        name: "📋 TOML-Syntax prüfen"
      - id: debug-statements
        name: "🐛 Keine Debug-Statements (pdb, breakpoint)"

14 Änderungshistorie (Review-Fixes)

Diese Version enthält alle Korrekturen aus dem externen Code-Review vom 21. Juni 2026.