code guidelines

GUIDELINES.md

@@ -0,0 +1,43 @@
+# 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.