---
description: Dart language coding standards and conventions. Apply to ALL Dart files.
globs: "**/*.dart"
---

# Dart Coding Standards

## Naming Conventions
- PascalCase for classes, enums, typedefs, extensions.
- camelCase for variables, functions, methods, parameters.
- snake_case for file and directory names.
- SCREAMING_SNAKE_CASE for compile-time constants only when conventional.
- Start functions with a verb: fetchUser(), saveSettings(), isValid().
- Use boolean prefixes: isLoading, hasError, canDelete, shouldRefresh.
- Use complete words, avoid abbreviations (except API, URL, i/j for loops).

## Functions
- Short, single purpose, < 20 lines.
- Arrow syntax for simple one-line functions.
- Named parameters for > 2 parameters.
- Default parameter values instead of null checks.
- Reduce parameters using parameter objects (RO-RO pattern).
- Single level of abstraction per function.
- Early return to avoid deep nesting.

## Classes
- Follow SOLID principles.
- Prefer composition over inheritance.
- Small classes: < 200 lines, < 10 public methods, < 10 properties.
- Declare interfaces (abstract classes) for contracts/repositories.
- Use factory constructors for complex initialization.

## Data & Immutability
- Prefer immutable data structures.
- Use final for fields that don't change.
- Use const for compile-time constants.
- Encapsulate data in composite types (avoid primitive obsession).
- Use Freezed for complex immutable state classes.

## Null Safety
- Write soundly null-safe code.
- Avoid ! operator unless value is guaranteed non-null.
- Use ?. and ?? operators appropriately.
- Prefer required named parameters over nullable ones.

## Error Handling
- Use try-catch for expected exceptions.
- Create custom exception classes for domain-specific errors.
- Never catch generic Exception without rethrowing or logging.
- Use Either<Failure, T> for functional error handling in repositories.

## Async
- Use async/await (not .then() chains).
- Use Future for single async operations.
- Use Stream for sequences of async events.
- Handle errors in every async operation.
- Cancel subscriptions in dispose().

## Code Organization
- One primary export per file.
- Group related libraries in the same folder.
- Use part/part of sparingly; prefer separate files.
- Import order: dart:, package:, relative imports.

## Documentation
- /// for all public API doc comments.
- First line: concise summary ending with period.
- Explain WHY, not WHAT.
- Use backtick fences for code samples.
- Place doc comments before annotations.