typetype-coding-standards

TypeType Coding Standards

Python

Import Order

One blank line between groups:

# 1. Standard library
import os
import sys

# 2. Third-party
from PySide6.QtCore import QUrl
import darkdetect

# 3. Local
from src.backend.application.gateways.score_gateway import ScoreGateway

Naming

Type	Convention	Example
Class	PascalCase	TextSourceGateway, LoadTextUseCase
Function/Variable	snake_case	load_text, source_key
File	snake_case / lowercase with underscores	text_source_gateway.py
Constant	UPPER_SNAKE_CASE	MAX_RETRIES, DEFAULT_TIMEOUT

Type Hints

ALL function parameters and return values MUST have type hints.

# Good
def load_text(self, source_key: str) -> str | None: ...

# Bad - missing
def load_text(self, source_key): ...

Line Length

• Max 88 chars (ruff default)
• Long imports/URLs allowed to exceed

Exceptions

• External I/O (network/file) MUST have exception handling
• Network exceptions: infrastructure/network_errors.py
• Global → user message: application/exception_handler.py

Qt/QML

Python/Qt

• Use Signal() + @Slot() for connections
• Blocking operations MUST run in background worker (QRunnable via QThreadPool)
• Follow BaseWorker pattern

QML

• Use Property + notify signal for reactive updates
• Prefer signal-slot over direct property access
• Colors: Theme.currentTheme.colors.*
• Normal UI font follows the global app font set in main.py; only dedicated reading/typing areas should set a custom fontFamily (current example: TypingPage.qml uses LXGW WenKai for正文区)
• Name conflict: import RinUI as Rin then Rin.TextArea

Architecture Rules (MUST Follow)

1. Domain Services are pure → NO import PySide6 in domain/services/
2. Dependency inward only → outer → inner, never reverse
3. Program to interface → use Ports (protocols) for external deps
4. Routing in Application → Adapters don't make routing decisions