style-guide

Dedalus Style Guide: Quick Reference

Hard Limits

• Functions: 70 lines max
• Files: 500 lines max (excluding inline tests)
• Nesting: 3 levels max
• Arguments: 5 max (excluding self/cls)
• PRs: 200 changed LOC max

I/O Convention

# I/O function: io: Io as first parameter
async def fetch_user(io: Io, user_id: str) -> User | None: ...

# Pure function: no io parameter
def compute_discount(user: User, cart: Cart) -> Decimal: ...

Types

• No Any. Period. If you reach for Any, you have not modeled the domain.
• No object as a type annotation. It is Any in disguise.
• For heterogeneous JSON, use JSONValue, JSONObject, JSONPrimitive, or JSONArray from core.types.json. These are proper recursive RFC 8259 types. There is no excuse for dict[str, object] or dict[str, Any].
• No **kwargs: Any without justification.
• Use typed structures (dataclass, TypedDict, Pydantic) instead of dicts.
• Pydantic at boundaries, plain types internally.
• Replace anonymous tuples with frozen dataclasses or named types.

Functions

• Early returns instead of nesting
• One thing per function: if you need "and", split it
• Named parameters at call sites: fetch_user(io=io, user_id=uid)
• Return value in own variable for debuggability: result = ...; return result
• No chaining construction + method: Foo(x).bar() hides the instance. Split into foo = Foo(x) then result = foo.bar().
• Split compound assertions: assert a; assert b not assert a and b

Error Handling

• Specific exceptions with domain context: ChargeError(org_id, reason)
• Never catch bare Exception without # noqa: BLE001
• Never swallow with pass
• Namespace pattern: BillingError.ChargeError
• Result types for domain logic, try/except at boundaries

No Fallbacks

# Bad: silent, undebuggable
model = request.model or config.default_model or "gpt-4"

# Good: explicit precedence with early returns
def get_model(request, config):
    if request.model:
        return request.model
    if config.default_model:
        return config.default_model
    raise ValueError("model is required")