worldhopper/.serena/memories/code_style_and_conventions.md

Code Style and Conventions

Linting

• Uses package:flutter_lints/flutter.yaml - Flutter's recommended lint rules
• Configuration in analysis_options.yaml
• Run linter: flutter analyze
• All lints must pass before committing

Dart/Flutter Conventions

Naming

• Classes/Enums/Typedefs: PascalCase (e.g., OPDSFeed, DatabaseHelper)
• Variables/Functions/Parameters: camelCase (e.g., fetchFeed, serverId)
• Private members: Prefix with underscore (e.g., _database, _authService)
• Constants: lowerCamelCase for const variables (e.g., const defaultTimeout)
• Files: snake_case (e.g., opds_service.dart, server_list_screen.dart)

Widget Construction

• Use const constructors wherever possible for performance
• Use super.key for widget keys
• Mark widget fields as final
• Prefer StatelessWidget over StatefulWidget when no state is needed
• Use trailing commas for better formatting (especially in widget trees)

State Management - Riverpod

• Use riverpod_annotation with code generation for providers
• Provider files should have corresponding .g.dart files
• Use @riverpod annotation for provider functions
• Run flutter pub run build_runner build to generate provider code
• Consume providers using ref.watch() in widgets (via ConsumerWidget or Consumer)
• Use ref.read() for one-time reads in callbacks

Data Models - Freezed

• All data models use Freezed for immutability
• Include both .freezed.dart and .g.dart parts
• Use @freezed annotation for models
• Define fromJson factory for JSON deserialization
• Private constructor pattern: const ModelName._();
• Run flutter pub run build_runner build to generate model code

Database Patterns

• Singleton pattern for DatabaseHelper (DatabaseHelper.instance)
• Table definitions as static constants in table classes
• Use foreign key constraints
• Repository pattern for data access
• All database operations should be async

Service Layer

• Services are injectable via constructor parameters
• Default implementations provided with null coalescing
• Use Dio for HTTP operations with proper error handling
• Parser services are separate from network services

Code Structure

• Imports: Organize as package imports, relative imports, then part files
• Theme: Uses Material 3 (useMaterial3: true)
• Documentation: Use /// for public API documentation comments
• Regular comments: Use // for implementation comments
• Debug output: Use debugPrint() instead of print()

Type Annotations

• Prefer explicit types for public APIs and class fields
• Type inference acceptable for local variables when obvious
• Always specify return types for functions and methods

Error Handling

• Use try-catch for async operations that may fail
• Provide meaningful error messages
• Handle HTTP errors appropriately
• Log errors with debugPrint() for debugging

Authentication

• Credentials stored encrypted in SQLite
• Authentication handled via AuthService
• Dio clients created per-server with auth configuration

File Organization

• Group related functionality in directories (screens, services, models, etc.)
• Keep widget files focused on single widgets or screens
• Extract reusable widgets to lib/widgets/
• Screen-specific widgets can go in screens/<feature>/widgets/

Code Generation

Run code generation after modifying:

• Models with @freezed annotation
• Providers with @riverpod annotation
• Models with @JsonSerializable annotation

Command: flutter pub run build_runner build --delete-conflicting-outputs