Dart Coding Guidelines

• Write concise, technical Dart code with accurate examples

• Use functional and declarative programming patterns

• Choose descriptive variable names with auxiliary verbs (e.g., isLoading , hasError )

• Keep functions and classes short (< 200 lines, < 10 public methods)

• Always use English for code and documentation

• Use PascalCase for classes, camelCase for variables and functions, snake_case for files, UPPERCASE for constants

• Use arrow syntax for simple methods and expression bodies for one-line getters/setters

• Avoid nesting blocks; prefer early checks and returns

• Pass and return parameters using RO-RO (Receive Object, Return Object)

• Avoid magic numbers; use well-named constants

• Follow an 100-character line limit and use trailing commas for better formatting

• Follow the lint rules set for this project (all_lint_rules.yaml and analysis_options.yaml )

• Strong Typing: Strictly prohibit dynamic . Use Object? or explicit types.

• Cascade Pattern: Use cascade notation (.. ) for cleaner initialization of complex objects where appropriate.

• Null Safety: Avoid ! null assertion operator unless value is guaranteed non-null by control flow. Prefer pattern matching.

• Switch Expressions: Prefer exhaustive switch expressions (no break needed in Dart 3).

Code Clarity & Maintenance

• 300-Line Limit: Strictly flag any file exceeding 300 lines (excluding tests) for decomposition into separate files.

• Guard Clauses: Use early returns (e.g., if (user == null) return; ) to reduce indentation.

• Meaningful Naming: Use intention-revealing names. Boolean variables MUST use prefixes like is , has , should .

• Disposable Lifecycle: TextEditingController , ScrollController , FocusNode , StreamSubscription , AnimationController , etc. MUST be late initialized in initState() and disposed in dispose() . Inline initialization is STRICTLY prohibited to prevent memory leaks and ensure proper lifecycle management.

• No Print Statements: STRICTLY prohibit print() . Use AppLogger for all logging.

• Localization: Zero hardcoded user-facing strings. Use .arb files and context.l10n .

• Reuse: If a widget or code block is used multiple times, extract it into a common widget or utility. Place shared widgets in core/views/widgets .

• Library Organization: Group related classes within the same library file. For large libraries, export smaller private libraries from a single top-level library.

Anti-Patterns

• No Heavy Work in build() : Move sorting, filtering, and expensive computations to initState() or didUpdateWidget() . Never compute in every rebuild.

• No Nested ScrollViews in the same direction. Use CustomScrollView with Slivers instead.

• No Unnecessary Containers: Prefer SizedBox , Padding , DecoratedBox over Container .

• Widget Extraction: STRICTLY prohibit private _build*() methods that return widgets. Extract into separate widget classes.

Documentation

• No Redundant Comments: Do not explain WHAT code does. Explain WHY (intent).

• Simple & Informative: Comments MUST be concise, informative, and understandable. Avoid "wall of text".

• No History Comments: STRICTLY prohibit comments like "fixed X" or "updated Y". Git history is the source of truth.

• Follow official documentation for best practices.

• Document public classes and methods with clear descriptions, parameters, return values, and a code snippet taken from the codebase

• Comment briefly only complex logic and non-obvious code decisions