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.

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.

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