44 lines
1.6 KiB
Markdown
44 lines
1.6 KiB
Markdown
|
# swarm — Project Guidelines
|
||
|
|
|
||
|
|
## Actor Model Conventions
|
||
|
|
|
||
|
|
- **One sealed hierarchy per actor.** Define a `sealed class FooMessage` for
|
||
|
|
commands and a `sealed class FooResult` for responses. Every concrete variant
|
||
|
|
is a `final class`.
|
||
|
|
|
||
|
|
- **Handler mixin, not extension.** Actors implement `Handler<M, A>` via `with`,
|
||
|
|
never via `extends` or `implements`.
|
||
|
|
|
||
|
|
- **Factory tear-off for construction.**
|
||
|
|
```dart
|
||
|
|
final actor = Actor.create(FooActor.new);
|
||
|
|
```
|
||
|
|
Never pass an already-constructed handler instance across isolate boundaries.
|
||
|
|
|
||
|
|
- **Skip `init()` and `close()` when there is nothing to initialise or release.**
|
||
|
|
Override them only when the actor holds persistent resources (sockets,
|
||
|
|
database handles, etc.).
|
||
|
|
|
||
|
|
- **Errors propagate as exceptions.** Throw inside `handle()`; the `actors`
|
||
|
|
runtime wraps isolate errors in `RemoteErrorException` on the caller side.
|
||
|
|
Result-type error variants are only justified across network/serialisation
|
||
|
|
boundaries.
|
||
|
|
|
||
|
|
## Code Style
|
||
|
|
|
||
|
|
- **Comment only when intent is not obvious.** Skip doc comments on
|
||
|
|
self-explanatory members (`final String path`, `const FileSaved()`, etc.).
|
||
|
|
|
||
|
|
- **Prefer `const` constructors and declarations** wherever the linter suggests.
|
||
|
|
|
||
|
|
- **No `public_member_api_docs` lint rule.** Forced doc comments on every public
|
||
|
|
member produce noise, not signal.
|
||
|
|
|
||
|
|
- **`prefer_final_fields`, `avoid_print`, `sort_pub_dependencies`** are enabled.
|
||
|
|
|
||
|
|
## Content Types
|
||
|
|
|
||
|
|
- Actors deal in plain Dart types (`String`, `int`, `Map`, …) or simple value
|
||
|
|
objects. Binary data (`Uint8List`) warrants a separate actor rather than
|
||
|
|
overloading an existing one.
|