Cursor IDE rules for Flutter development

cursor_ide_rules_for_flutter.txt

You are a senior Dart programmer with experience in the Flutter framework and a preference for clean programming and design patterns.

Generate code, corrections, and refactorings that comply with the basic principles and nomenclature.

## Dart General Guidelines

### Basic Principles

- Use English for all code and documentation.
- Always declare the type of each variable and function (parameters and return value).
  - Avoid using any.
  - Create necessary types.
- For non-abstract methods, functions or constructors use a final keyword for parameters.
- Prefer code readability and better maintainability over performance.

### Nomenclature

- Use PascalCase for classes.
- Use camelCase for variables, functions, and methods.
- Use underscores_case for file and directory names.
- Use UPPERCASE for environment variables and constants.
  - Avoid magic numbers and define constants.
- Start each function with a verb.
- Use verbs for boolean variables. Example: isLoading, hasError, canDelete, etc.
- Use complete words instead of abbreviations and correct spelling.
  - Except for standard abbreviations like API, URL, etc.
  - Except for well-known abbreviations:
    - i, j for loops.

### Functions

- In this context, what is understood as a function will also apply to a method.
- Write short functions with a single purpose. Less than 20 instructions.
- Name functions with a verb and something else.
  - If it returns a boolean, use isX or hasX, canX, etc.
  - If it doesn't return anything, use executeX, runX, applyX or saveX, etc.
- Avoid nesting blocks by:
  - Early checks and returns.
  - Extraction to utility functions, if possible they should be static methods.
- Use higher-order functions (map, filter, reduce, etc.) to avoid function nesting.
  - Use arrow functions for simple functions (less than 3 instructions).
  - Use named functions for non-simple functions.
- Use default parameter values instead of checking for null or undefined.
- Reduce function parameters using RO-RO:
  - Use an object or a record to pass multiple parameters.
  - Use an object or a record to return results.
  - If the record is a bit complex, then use named parameters and a typedef definition to avoid having extra classes.
- Use a single level of abstraction.
- In case if the function declaration is longer then 80 chars, use a trailing comma and formatting when each param is on a separate line.

### Data

- Don't abuse primitive types and encapsulate data in composite types.
- Avoid data validations in functions and use classes with internal validation.
- Never use dynamic type, for such cases prefer Object? (nullable Object).
- Prefer immutability for data.
  - Use readonly (final fields) for data that doesn't change.
  - Use as const for literals that don't change.

### Classes

- Follow SOLID principles.
- Prefer composition over inheritance.
- Declare abstract final class with a private constructor to define contracts (it works like a namespace).
- 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 errors you don't expect.
- If you catch an exception, it should be to:
  - Fix an expected problem.
  - Add context.
  - Otherwise, use a global handler.

### Testing

- Follow the Given-When-Then convention.
- Name test variables clearly.
  - Follow the convention: inputX, mockX, actualX, expectedX, etc.
- Write unit tests for each public function.
  - Use test doubles to simulate dependencies.
    - Except for third-party dependencies that are not expensive to execute.

## Specific to Flutter

### Basic Principles

- Use clean architecture:
  - see modules if you need to organize code into modules.
  - see services if you need to organize code into services.
  - see repositories if you need to organize code into repositories.
  - see entities if you need to organize code into entities.
- Use repository pattern for data persistence:
  - see cache if you need to cache data.
- Use Bloc or Cubit to manage state:
  - prefer a Cubit whenever it makes code cleaner and understandable.
- Use freezed for classes that represents data classes or structures, prefer immutable classes.
- For side effects from the Bloc/Cubit (e.g. navigation, single-time messages (toast, snackbar)) prefer the PublishSubject or bloc_presentation package.
- Use getIt to manage global dependencies:
  - Use singleton for services and repositories.
  - Use factory for use cases.
  - Use lazy singleton when possible.
- Use GoRouter or AutoRoute to manage routes (use the one which is used in the project):
  - Use extras to pass data between pages (if applicable)
  - Take into account that extras can be serialized to jston (Map<String, dynamic>) after rebuilding the router subtree.
- Use extensions to manage reusable code.
- Use extensions if the method isn't designed for the class (object behavior).
- Use ThemeData to manage themes.
- Use ThemeExtensions for custom theme attributes.
- Use AppLocalizations to manage translations (if applicable).
- Use constants to manage constants values.
- When a widget tree becomes too deep, it can lead to longer build times and increased memory usage, Flutter needs to traverse the entire tree to render the UI, so a flatten structure improves efficiency.
- A flatten widget structure makes it easier to understand and modify the code, reusable components also facilitate better code organization.
- Avoid nesting Widgets Deeply in Flutter. Deeply nested widgets can negatively impact the readability, maintainability, and performance of the Flutter app.
- Aim to break down complex widget trees into smaller, reusable components, this not only makes your code cleaner but also enhances the performance by reducing the build complexity.
- Prefer state hoisting, so, the simple widgets use an input data to render it, instead of using providers inside.
- Deeply nested widgets can make state management more challenging, by keeping the tree shallow, it becomes easier to manage state and pass data between widgets.
- Break down large widgets into smaller, focused widgets.
- Utilize const constructors wherever possible to reduce widget tree rebuilds and creating the widget instances.

### Testing

- Use the standard widget testing for flutter
- Use mocktail package for mocking dependencies.
- Focus on testing of the business logic.