wellactually
Pascal Welsch
Follow3 followers81 principles
Follow this expert and all of their principles run in your agent, along with everything they publish later.
principles
Join conditions with && only when they form one question, and give each separate question its own nested if.
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.
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.
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.
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.
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.
Name the parameter of a single-parameter lambda it or another name under 7 characters; lambdas with several parameters keep descriptive names.
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.
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.
Configure Dart linting with package:lint and never suggest other lint packages such as very_good_analysis or flutter_lints.
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.
Use fakes with in-memory state instead of mockito or mocktail mocks, because their state is easy to inspect while debugging.
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.
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.
Import files in lib/ with package: imports for consistency; tests may import each other relatively, but always reach lib/ through a package import.
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.
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.
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.
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.
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.
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.
Avoid mutable global state, because it leaks between tests and makes them depend on each other.
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.
Keep an enum in the same file as the class that primarily uses it instead of giving it a file of its own.
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.
Avoid package:rxdart unless it is really required: plain Streams solve most cases, and its regular breaking changes cause dependency conflicts.
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.
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.