| name | write-dart |
| description | Write, review, or refactor correct, idiomatic Dart code. Use for Dart source, packages, snippets, tests, public APIs, documentation examples, and modern language features. Pair with the write-flutter skill for Flutter-specific concerns. |
Write Dart
Produce clear, correct, idiomatic Dart.
Reference the write-technical-docs skill when authoring
explanatory prose and documentation comments.
Two principles guide the code rules:
- Be consistent. Make different-looking code mean something different.
- Be brief. Prefer concise Dart idioms, but don't make code dense.
In the references, DO and DON'T are near-absolute,
PREFER and AVOID are strong defaults,
and CONSIDER requires judgment.
Match the project
- Treat the conventions in this skill as the repository defaults.
Follow applicable
analysis_options.yaml files for additional requirements.
- Before using a recent language feature,
check the lower SDK constraint in
pubspec.yaml.
The installed SDK might support syntax that the package doesn't.
Core defaults
Apply these high-frequency rules while writing.
Naming
- Use
UpperCamelCase for types and extensions,
lowerCamelCase for members, variables, and constants,
and lowercase_with_underscores for files, packages, and import prefixes.
For example, write defaultTimeout, never DEFAULT_TIMEOUT.
- Name booleans as positive, non-imperative verb phrases
such as
isEmpty and canClose.
- Name value-returning members as noun phrases such as
pageCount.
- Name side-effecting functions as imperative verbs such as
removeLast().
Never prefix an accessor with get.
Types
- Annotate return and parameter types on function and method declarations.
Signatures are API documentation.
- Don't annotate types that inference can determine:
initialized locals, lambda parameters, initializing formals,
and inferable type arguments.
- Use
Object? to mean "any value".
Reserve dynamic for deliberately disabling static checking.
Null safety and immutability
- Prefer
final over var for variables that aren't reassigned,
including locals, fields, and top-level variables.
- When a constructor supports it,
make the constructor
const.
- Use
late when initialization genuinely happens after construction
or lazily on first access.
If code needs to ask whether initialization happened,
use a nullable type and check for null instead.
- When absence has no meaning distinct from "empty",
return an empty collection or stream instead of
null.
Use a nullable return type only when absence is a real state
that callers must distinguish.
Control flow and errors
- Switch over enums and sealed types without a
default or _ case,
so adding a new case becomes a compile-time error everywhere it's handled.
- Catch specific types with
on.
Never discard errors without handling them.
Use rethrow, not throw e.
Throw Error subtypes only for programming bugs and
don't catch them for recovery.
Functions and async
- Prefer named parameters for booleans
and for arguments that are unclear at the call site.
For example, write
resize(width: 320, keepAspect: true).
- Use
async and await over raw .then() chains,
and account for every returned Future.
Await or return the future.
If an operation is intentionally detached,
wrap it in unawaited(operation())
and make its error behavior deliberate.
Write maintainable code
- Keep functions small and single-purpose.
Prefer a clear name to an explanatory comment.
- Use the type system to prevent invalid states with
sealed class hierarchies, extension types, and non-nullable types
instead of runtime conventions and documentation.
- Avoid unnecessary complexity:
don't add parameters, options,
or abstractions without a concrete requirement.
Use modern Dart
Use modern features when they improve type safety or remove boilerplate
without obscuring the example.
Check the package's SDK constraint,
then read Modern Dart idioms
for version requirements and examples.
Validate
When an SDK and project are available,
format changed files, run dart analyze, and run the relevant tests.
Use flutter test instead of dart test for Flutter code.
For standalone snippets, check the relevant reference and
compile them when practical.
References
Read only the references relevant to the code you're writing or reviewing:
- Style:
Naming identifiers, organizing imports and exports,
and layout decisions the formatter doesn't handle.
- Documentation:
Read before writing doc comments or reviewing comment quality.
- Usage:
Imports, null handling, strings, collections, members,
constructors, errors, and async.
- Public API design:
Public API design, including names, classes, signatures,
annotations, parameters, and equality.
- Modern Dart idioms:
Recent language features, version constraints, and examples.
