wellactuallyLibrary
Every public principle, from every expert. A principle runs for you once its expert, or a collection that holds it, is on your advisory board. To find people instead, go to Explore.
Give a PR a verb-first title and a short description of the problem and the change, with examples or screenshots, and leave out fluff and test-plan lists.
Write markdown with one sentence per line, no wrapping, dash bullets, ATX headings and tagged code fences, and run markdownlint-cli2 after every edit.
Write a short, capitalized, imperative commit subject without a period, and add a body that explains what changed and why when the diff cannot.
Join conditions with && only when they form one question, and give each separate question its own nested if.
Tests must exercise code from lib; never reproduce the implementation or mock the production class under test.
Before creating a new test file or test helper class, check whether an existing one already covers that unit and extend it instead.
Extract a function only when it names a stable domain concept, is reused, hides real complexity or is worth testing on its own.
Give each method of a fake a nullable override function field placed right above it, so a test can change one behavior without a new fake.
Avoid the late keyword, because it turns a compile time check into a runtime LateInitializationError; initialize in the constructor or use a nullable type.
Keep model objects immutable and hold changing state, such as which items are checked, separately, because mutating a field may not trigger setState and leaves the UI stale.
Give a lambda that spans several lines a curly-brace body instead of =>, because it needs less indentation and you can set breakpoints inside it.
Test a page by launching the app and navigating to it, not by wrapping it in its own MaterialApp, so routes, providers and results are tested for real.
Prefer switch, polymorphism, collection functions or early returns over if-else, and keep if-else for two equally weighted branches.
Catch the stack trace together with the error and pass both along, because an error without its stack trace says what failed but not where.
Read the time through clock.now() from package:clock, so tests can control it with fakeAsync or withClock.
Log through package:chirp, or developer.log in a Flutter app without chirp, and never print(), because print loses the error and stack trace.
Parse JSON with package:deep_pick instead of code generation or casting the Map from jsonDecode by hand, because it is type safe, null aware and needs no build_runner.
Transform collections with .map(), .where() and .fold() instead of filling an empty list in a loop, because declarative code is shorter and easier to read.
Inject dependencies instead of reaching for a singleton, so tests can replace them with a fake or a mock.
Keep ternaries on one line; when a condition spans lines, use an immediately invoked function or if-else so each branch stays readable and debuggable.
Replace if-else and multi-line or nested ternaries in build methods with a Builder that uses early returns, so each conditional state is easy to read.
Give reusable widgets Widget parameters with a DefaultTextStyle instead of String parameters for user-facing text, so callers can pass icons, rich text or their own style.
Write short dartdoc for public APIs that explains usage, context and non-obvious behavior, and never restates what the name already says.
Inspect local conventions before adding public API, state management, abstractions or configuration.
Name a Dart file after the main class it contains, and keep that class at the very top, so the file name tells the reader what is inside.
Do not use String or List<String> for statuses, roles, categories or options; use an enum, a class with static values or an extension type.
Put a guard clause's return or throw on its own line inside braces, so exits stay visible and can take a breakpoint.
Avoid setUp and tearDown in tests; create state locally or in factory functions and register cleanup with addTearDown next to the resource.
Catch with error and stackTrace, and forward both through the logger’s named arguments.
Describe what changed and why in the commit subject instead of prefixing it with feat:, fix: or chore:, which add noise the diff already shows.
Back data models that wrap API maps with a Rekord and typed getters parsed lazily through deep_pick, so a missing or broken field only fails when it is read.
Keep reactive state in signals scoped to a controller, preferably state_beacon, instead of ChangeNotifier or ValueNotifier, so derived values cannot go stale.
Use braces and put every control-flow body on a separate line.
Avoid build_runner and code generation in Dart; write the code once instead, and do not suggest freezed unless the project already depends on it.
In Flutter mobile apps, tapping the background outside a text field must dismiss the keyboard by removing focus; check this for every field you add.
Name the parameter of a single-parameter lambda it or another name under 7 characters; lambdas with several parameters keep descriptive names.
Write one prose sentence per source line and apply the convention only to text being edited.
Racing a timer against a future does not cancel the loser, which keeps its socket or connection; cancel at the source with a real primitive.
Extract UI sections into public widget classes instead of Widget _buildX() methods, so tests can find them by type and the tree stays easy to query.
When behavior, API or architecture already described in docs changes, update the documentation in the same change.
Put the class a file is named after at the very top of the file, above its helper classes, enums and extensions, so readers meet the main type first.
Configure Dart linting with package:lint and never suggest other lint packages such as very_good_analysis or flutter_lints.
When one condition picks between UI variants, branch once and build one complete widget per variant instead of repeating the condition on every property.
Write a private helper that does not touch instance state as a top-level function in the file, not a static member, because library privacy already scopes it.
For async_return_with_no_await, add await and preserve the async method.
Use fakes with in-memory state instead of mockito or mocktail mocks, because their state is easy to inspect while debugging.
Avoid the if-case pattern matching syntax and write a plain type and length check instead, because many developers still find if-case hard to read.
In widgets and other classes with dispose(), delay work with a Timer you cancel in dispose(), because Future.delayed cannot be cancelled.
Declare variables final or const unless they are reassigned, so a var signals real reassignment; this does not apply to for-loop headers or function parameters.
Use a named class instead of a record for public return, parameter and field types, because adding a field to a record breaks every caller that destructures it.
Check every code claim against current source and maintain the index and related-document links.
Import files in lib/ with package: imports for consistency; tests may import each other relatively, but always reach lib/ through a package import.
Write a changelog for its reader: categorized, linked entries listing every changed symbol for developers, and short news headlines about benefits for app users.
Write copyWith as a typed function getter backed by a sentinel default, so callers can set nullable fields back to null without losing type safety.
Export a package's public symbols with explicit show clauses, so the public API is a deliberate list and internals do not leak.
Give the main widget of every widget file a dartdoc comment that says where it is used and what makes it unique, not a restatement of its name.
Two feature files must not import each other; move the shared concept into something both depend on, or inline it, so each can be read and deleted alone.
Fix async_return_with_no_await by adding the missing await and keeping async, because the next change will likely need another await anyway.
Use package:provider with context.read and context.watch for state management, instead of riverpod or get_it.
Keep functions free of side effects unless one is explicitly necessary, so they stay easy to reason about and test.
Handle Flutter forms with package:reactive_forms instead of Form, TextFormField and TextEditingController, so form state and validation live in one model.
Put the final casing of user-visible text in the localization resource instead of calling toUpperCase() on it, because Dart's casing is wrong for some languages.
Copy collections into a result object and expose them unmodifiable, and keep the data that explains a failure on the typed reason itself, so callers cannot mutate or misread it.
Organize code by feature and call repositories directly, because UseCase and layer-first folders add indirection and boilerplate without value.
Prefer composition over inheritance and do not write subclasses that enhance a base class, because they get complex and hard to maintain.
Avoid sealed classes and enums in a package's public API when cases may grow, because each new case breaks every caller's exhaustive switch.
Wrap only the one call you expect to throw FormatException, StateError, TimeoutException and similar generic types, because a wide try cannot tell which statement threw.
Use a private top-level _setup() returning a named record instead of shared late fixtures and setUp().
Before writing a fallback, decide what the user sees when it triggers, and never let a substitute value pass for the real thing.
Write a plain for loop instead of forEach, because forEach allocates an unnecessary lambda; for transformations use map, flatMap or reduce.
Report a failed operation by throwing, not by returning false, so the error and its stack trace reach the caller and cannot be silently ignored.
Write URLs and route paths as complete literal strings, so searching the codebase for a path from a log or bug report finds the code.
Use package:context_plus to bind objects to widget scopes and watch them, instead of provider, riverpod, get_it or hand-written InheritedWidgets.
Keep a StatefulWidget and its State class next to each other, with no function, variable or other class declared between them.
Return early from guards to flatten nesting, but keep symmetric forks as if-else and independent checks as positive parallel if blocks.
Name a widget that a route pushes *Page in *_page.dart, never *Screen, because Flutter already calls a route's configuration a Page and a screen is hardware.
A TypeScript enum emits runtime code and breaks type stripping; a union of string literals gives the same safety with nothing emitted.
Import and exercise the real code from lib/ in tests and never copy or reimplement production logic in a test file, because a test of a copy passes while production is broken.
Name intermediate values and declare them close to their use, so debuggers, logs and stack traces can show the state when code fails.
Avoid mutable global state, because it leaks between tests and makes them depend on each other.
Treat a deleted, commented-out or skipped test as a red flag that needs a reason: fix it, delete it with a tracking issue, or skip it with an issue number.
Keep an enum in the same file as the class that primarily uses it instead of giving it a file of its own.
Keep a constant in the file that uses it, or the one it belongs to most, instead of collecting constants in a globals file; only cross-module constants go to main.dart.
Return Future<T> and let failures throw instead of returning Future<Either<T>>, because a Future can fail anyway and Either only adds complexity and false safety.
Never send analytics events from a Flutter build() method, directly or through a helper, because rebuilds are not user events and produce duplicate counts.
Do not use package:bloc or flutter_bloc for state management; streams are hard to test, and a synchronous ChangeNotifier is simpler for most code.
Generate @genq models with the plain genq CLI from their package directory.
Use the owning package’s docs directory, outside lib or src.
Never hand-edit or reformat generated Dart output; use the owning generator.
Scenarios call robot actions; robots own selection, gestures, pumping and typed observability.
Start with empty fake storage and write seed state through the real persistence service.
Use package imports within lib and keep dart, package and relative directives in ordered groups.
When two public paths claim the same behavior, add tests that pin them to each other on the tricky inputs so they cannot drift apart.
Avoid package:rxdart unless it is really required: plain Streams solve most cases, and its regular breaking changes cause dependency conflicts.
Carry one context object through a request and emit a single wide log line when it ends, instead of scattering log calls that need a join.
Make a function public only when it is a documented internal API; a helper that one other file needs belongs next to that caller as a private function.
Become an expert
Turn the advice you keep giving in code reviews into a principle that runs inside other people's agents. The guide takes you from an idea to a released principle, in the browser or in your editor.