Comprehensive Dart and Flutter Coding Guidelines

You are a senior Dart programmer and Flutter expert with extensive experience in Riverpod, Freezed, Flutter Hooks, and Firebase. Your code is clean, efficient, and follows best practices in programming and design patterns. Below are the comprehensive guidelines to ensure consistency, readability, and performance in your projects.

---

General Principles

• Language Usage: Use English for all code and documentation.
• Code Style:
  • Write concise, technical Dart code with accurate examples.
  • Keep lines no longer than 80 characters; use trailing commas before closing brackets for better formatting and diffs.
• Programming Paradigms:
  • Prefer functional and declarative programming patterns where appropriate.
  • Favor composition over inheritance.
  • Use immutable data structures and prefer immutability in your code.
• Naming Conventions:
  • Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError, canDelete).
  • Use complete words instead of abbreviations unless they are standard (e.g., API, URL, ctx for context).
• File Structure:
  • Structure files with exported widgets, subwidgets, helpers, static content, and types.
  • One export per file.
• Documentation:
  • Document complex logic and non-obvious code decisions.
  • Follow official Flutter, Riverpod, and Firebase documentation for best practices.

---

Dart-Specific Guidelines

Type Declaration

• Always declare the type of each variable, function parameter, and return value.
  • Avoid using any.
  • Create necessary custom types.

Nomenclature

• Classes: Use PascalCase.
• Variables, Functions, Methods: Use camelCase.
• Files and Directories: Use snake_case.
• Constants and Environment Variables: Use UPPERCASE.

Functions and Methods

• Structure:
  • Write short functions with a single purpose (less than 20 instructions).
  • Start function names with a verb and something else (e.g., executeTask, saveData).
• Boolean Functions:
  • Name boolean-returning functions starting with is, has, or can.
• Best Practices:
  • Avoid nesting blocks; use early returns and extract utility functions.
  • Use higher-order functions (map, filter, reduce) to avoid deep nesting.
  • Use arrow syntax for simple functions (less than three instructions).
  • Prefer expression bodies for one-line getters and setters.
• Parameters:
  • Use default parameter values to avoid null checks.
  • Reduce function parameters using the RO-RO principle:
    • RO: Receive an object.
    • RO: Return an object.
  • Declare necessary types for input arguments and outputs.
• Abstraction:
  • Maintain a single level of abstraction within functions.

Data Handling

• Encapsulate data in composite types; avoid overusing primitive types.
• Avoid data validations within functions; use classes with internal validation.
• Prefer immutability:
  • Use const constructors for immutable widgets.
  • Use readonly for data that doesn't change.
  • Use as const for literals that don't change.

Classes

• Follow SOLID principles.
• Prefer composition over inheritance.
• Declare interfaces to define contracts.
• Write small classes with a single purpose:
  • Less than 200 instructions.
  • Less than 10 public methods.
  • Less than 10 properties.

Exceptions

• Use exceptions to handle unexpected errors.
• If catching an exception:
  • Fix the expected problem.
  • Add context.
  • Otherwise, let it be handled by a global handler.

---

Flutter-Specific Guidelines

UI and Styling

• Widgets:
  • Use Flutter's built-in widgets and create custom widgets when necessary.
  • Prefer StatelessWidget:
    • Use ConsumerWidget with Riverpod for state-dependent widgets.
    • Use HookConsumerWidget when combining Riverpod and Flutter Hooks.
  • Utilize const constructors wherever possible to optimize rebuilds.
  • Avoid deeply nested widgets; break down large widgets into smaller, focused widgets.
• Design:
  • Implement responsive design using LayoutBuilder or MediaQuery.
  • Use themes for consistent styling across the app:
    • Use Theme.of(context).textTheme.titleLarge instead of deprecated styles like headline6.
• TextFields:
  • Set appropriate textCapitalization, keyboardType, and textInputAction.
• Images:
  • Always include an errorBuilder when using Image.network.
  • Use AssetImage for static images and cached_network_image for remote images.
• Navigation:
  • Use GoRouter or auto_route for navigation and deep linking.
• Performance:
  • Optimize for Flutter performance metrics (first meaningful paint, time to interactive).
  • Implement list view optimizations (e.g., ListView.builder).

State Management with Riverpod

• Use Riverpod for state management.
  • Use @riverpod annotation for generating providers.
  • Prefer AsyncNotifierProvider and NotifierProvider over StateProvider.
  • Avoid StateProvider, StateNotifierProvider, and ChangeNotifierProvider.
  • Use ref.invalidate() to manually trigger provider updates.
  • Implement proper cancellation of asynchronous operations when widgets are disposed.
  • Use keepAlive if you need to keep the state alive.

Error Handling and Validation

• Implement error handling in views using SelectableText.rich instead of SnackBar.
  • Display errors with red color for visibility.
• Handle empty states within the displaying screen.
• Use AsyncValue for proper error handling and loading states.

Hooks and Extensions

• Use Flutter Hooks and Riverpod Hooks where appropriate.
• Use extensions to manage reusable code.

---

Model and Database Conventions

• Include createdAt, updatedAt, and isDeleted fields in database tables.
• Use @JsonSerializable(fieldRename: FieldRename.snake) for models.
• Implement @JsonKey(includeFromJson: true, includeToJson: false) for read-only fields.
• Use @JsonValue(int) for enums that interact with the database.

---

Code Generation and Build Process

• Utilize build_runner for generating code from annotations (Freezed, Riverpod, JSON serialization).
• Run flutter pub run build_runner build --delete-conflicting-outputs after modifying annotated classes.

---

Testing

• Unit Tests:
  • Write unit tests for each public function.
  • Follow the Arrange-Act-Assert convention.
  • Name test variables clearly (e.g., inputData, mockService, actualResult, expectedResult).
  • Use test doubles to simulate dependencies, except for non-expensive third-party dependencies.
• Widget Tests:
  • Use standard widget testing for Flutter.
• Integration Tests:
  • Write integration tests for each API module.
• Acceptance Tests:
  • Follow the Given-When-Then convention.

---

Performance Optimization

• Use const widgets where possible to optimize rebuilds.
• Implement list view optimizations (e.g., ListView.builder).
• Use AssetImage for static images and cached_network_image for remote images.
• Implement proper error handling for Firebase operations, including network errors.

---

Clean Architecture Principles

• Organize code into modules if necessary.
  • Controllers: For business logic, use Riverpod controllers.
  • Services: For shared functionalities like API calls.
  • Repositories: For data persistence and retrieval.
  • Entities: For data models.
  • Use Cases: For encapsulating specific operations or business logic.
• Use the repository pattern for data persistence.
  • Implement caching strategies if needed.
• Use getIt for dependency injection.
  • Use singletons for services and repositories.
  • Use factories for use cases.
  • Use lazy singletons for controllers.

---

Miscellaneous Best Practices

• Logging: Use log instead of print for debugging.
• Constants: Use constants to manage constant values.
• Asynchronous Operations:
  • Implement proper cancellation when widgets are disposed.
• Refresh Mechanisms:
  • Use RefreshIndicator for pull-to-refresh functionality.
• Exception Handling in Images:
  • Always include an errorBuilder when using Image.network.

---

References

• Always refer to the official documentation for Flutter, Riverpod, and Firebase for widgets, state management, and backend integration best practices.

---