Buma UI - Documentation

Remember to always follow Rules of Effective Dart HERE

Dart Style Guide

Follow the official Effective Dart Style Guide to write clean and consisten Dart code

Use lowerCamelCase for variables, functions, and parameters.
Use UpperCamelCase for class and enum names.
Use lowercase_with_underscores for file and library names.

For Example:

// Variables and functions
String userName = 'JohnDoe';
void calculateTotalPrice() {}

// Class and enum names
class UserProfile {}
enum Status { active, inactive }

// File and library names
// File: user_profile.dart

Naming Conventions (Clean Code)

Follow to write meaningful and descriptive names.

Use intention-revealing names for variables, functions, and parameters.
Avoid abbreviations and single-letter names unless they are widely understood (e.g., i for loop counters).

For Example:

// Good
class ShoppingCart {
  List<Item> items;
  void addItem(Item item) {}
}

// Bad
class SC {
  List<Item> i;
  void ai(Item item) {}
}

Modular Component Structure

Break your app into reusable and independent modules.

Organize code into (e.g., auth, home, profile)
Each module should contain its own UI, logic, services.

For Example:

lib/
├── modules/
│   ├── auth/
│   │   ├── auth_provider.dart
│   │   ├── auth_screen.dart
│   │   └── auth_service.dart
│   ├── home/
│   │   ├── home_provider.dart
│   │   ├── home_screen.dart
│   │   └── home_service.dart
├── main.dart

Event Naming Convention

Use descriptive names for events, prefixed with the action.

Use on as prefix for event handlers (e.g., onLoginButtonPressed)
Make the event name

For Example:

// Good
void onLoginButtonPressed() {}
void onUserProfileUpdated() {}

// Bad
void login() {}
void update() {}

Project Structure

Organize your project into layers (presentation, domain, data).

: Contains UI components (screens, widgets)
: Contains business logic and use cases
: Handles data sources (APIs, databases)

For Example:

.
└── feature/
    ├── presentation/
    │   ├── pages
    │   ├── widgets
    │   └── controllers
    ├── domain/
    │   ├── entities
    │   ├── usecases
    │   ├── params
    │   └── repositories
    └── data/
        ├── repositories
        ├── datasources/
        │   ├── remote
        │   └── local
        └── models

State Management (Riverpod)

Use for state management.

Riverpod is a library that simplifies dependency injection and state sharing
Use StateNotifierProvider for managing state

For Example:

// Provider
final userProvider = StateNotifierProvider<UserNotifier, User>((ref) {
  return UserNotifier();
});

// Notifier
class UserNotifier extends StateNotifier<User> {
  UserNotifier() : super(User.empty());

  void updateUserName(String name) {
    state = state.copyWith(name: name);
  }
}

// Usage
Consumer(builder: (context, ref, child) {
  final user = ref.watch(userProvider);
  return Text(user.name);
});

Documentation and Comments

Use /// for documentation and // for inline comments.

Use /// for documenting classes, methods, and properties
Use // for short, inline comments to explain complex logic

For Example:

/// Represents a user profile with a name and age.
class UserProfile {
  String name;
  int age;

  /// Creates a [UserProfile] with the given [name] and [age].
  UserProfile(this.name, this.age);
}

// Calculate the total price of items.
double calculateTotalPrice(List<double> items) {
  return items.reduce((sum, item) => sum + item);
}

Version Management

Use (major.minor.patch) and tools pubspec.yaml

: major.minor.patch(e.g., 1.0.0)
Use // for short, inline comments to explain complex logic

For Example:

/// Represents a user profile with a name and age.
class UserProfile {
  String name;
  int age;

  /// Creates a [UserProfile] with the given [name] and [age].
  UserProfile(this.name, this.age);
}

// Calculate the total price of items.
double calculateTotalPrice(List<double> items) {
  return items.reduce((sum, item) => sum + item);
}

Clean Code Principles

Follow Clean Code principles to write maintainable and scalable code pubspec.yaml

: Each class or function should have one responsibility
: Avoid code duplication
: Write simple and readable code

For Example:

// Good
class User {
  String name;
  int age;

  User(this.name, this.age);

  bool isAdult() => age >= 18;
}

// Bad
class User {
  String name;
  int age;

  User(this.name, this.age);

  void printDetails() {
    print('Name: $name, Age: $age');
    if (age >= 18) {
      print('Adult');
    } else {
      print('Not Adult');
    }
  }
}