swe-programming-dart

name	swe-programming-dart
description	Dart coding standards from authoritative docs/explanation/software-engineering/programming-languages/dart/ documentation

Dart Coding Standards

Purpose

Progressive disclosure of Dart coding standards for agents writing Dart code.

Authoritative Source: docs/explanation/software-engineering/programming-languages/dart/README.md

Usage: Auto-loaded for agents when writing Dart code. Provides quick reference to idioms, best practices, and antipatterns.

Prerequisite Knowledge

IMPORTANT: This skill provides demo-specific style guides, not educational tutorials.

You MUST understand Dart fundamentals before using these standards. Complete the demo Dart learning path first:

What this skill covers: demo naming conventions, framework choices, repository-specific patterns.

What this skill does NOT cover: Dart syntax, language fundamentals, generic patterns (those are in crud-fs-ts-nextjs).

Quick Standards Reference

Naming Conventions

Files and Packages: lowercase_with_underscores

• zakat_calculator.dart, murabaha_service.dart
• Package names: zakat_app, islamic_finance

Classes and Types: UpperCamelCase

• ZakatCalculator, MurabahaContract, PaymentStatus

Functions, Variables, Parameters: lowerCamelCase

• calculateZakat(), totalAmount, paymentDate

Constants: lowerCamelCase (not UPPER_CASE in Dart)

• const defaultNisab = 5000.0;
• static const zakatRate = 0.025;

Null Safety (Dart 3.0+)

Non-nullable by default:

// CORRECT: Non-nullable
String name = 'Ahmed';

// CORRECT: Nullable when needed
String? optionalEmail;

// CORRECT: Null-aware operators
String greeting = optionalEmail ?? 'Guest';
int? length = optionalEmail?.length;

WRONG: Null assertion without justification:

// WRONG: Unsafe null assertion
String definitelyPresent = possiblyNull!; // crashes if null

Error Handling

Typed exceptions:

// CORRECT: Typed exception hierarchy
class DomainException implements Exception {
  final String message;
  const DomainException(this.message);
}

class ZakatValidationException extends DomainException {
  const ZakatValidationException(super.message);
}

// CORRECT: Catch specific types
try {
  final result = await calculateZakat(wealth, nisab);
} on ZakatValidationException catch (e) {
  handleValidation(e);
} on DomainException catch (e) {
  handleDomain(e);
}

WRONG: Catching Object or dynamic:

// WRONG: Too broad
try {
  doSomething();
} catch (e) { // Catches everything including Errors
  print(e);
}

Async Patterns

Prefer async/await:

// CORRECT: async/await
Future<ZakatResult> calculateAsync(double wealth, double nisab) async {
  await Future.delayed(Duration(milliseconds: 100));
  return wealth >= nisab ? ZakatResult.due(wealth * 0.025) : ZakatResult.notDue();
}

// CORRECT: Stream for multiple values
Stream<Payment> paymentsStream(String contractId) async* {
  final payments = await repository.getPayments(contractId);
  for (final payment in payments) {
    yield payment;
  }
}

Immutability

Use final and const:

// CORRECT: Immutable class
class ZakatCalculation {
  final double wealth;
  final double nisab;
  final double amount;

  const ZakatCalculation({
    required this.wealth,
    required this.nisab,
    required this.amount,
  });
}

// CORRECT: const for compile-time constants
const zakatRate = 0.025;

Testing Standards

package:test structure:

import 'package:test/test.dart';

void main() {
  group('ZakatCalculator', () {
    late ZakatCalculator calculator;

    setUp(() {
      calculator = ZakatCalculator();
    });

    test('returns 2.5% when wealth above nisab', () {
      final result = calculator.calculate(10000, 5000);
      expect(result, equals(250.0));
    });

    test('returns 0 when wealth below nisab', () {
      final result = calculator.calculate(1000, 5000);
      expect(result, equals(0.0));
    });
  });
}

Security Practices

Input Validation:

• Validate all external input before processing
• Never log passwords, tokens, or financial details

Secrets Management:

// CORRECT: Use flutter_secure_storage
import 'package:flutter_secure_storage/flutter_secure_storage.dart';

final storage = FlutterSecureStorage();
await storage.write(key: 'api_token', value: token);

Comprehensive Documentation

Authoritative Index: docs/explanation/software-engineering/programming-languages/dart/README.md

Mandatory Standards (All Dart Code MUST Follow)

1. Coding Standards - Naming conventions, package organization, Effective Dart
2. Testing Standards - package:test, mockito, coverage >=95%
3. Code Quality Standards - dart analyze, lints, dart format
4. Build Configuration - pubspec.yaml, build_runner

Context-Specific Standards (Apply When Relevant)

1. Error Handling Standards - Typed exceptions, Result patterns
2. Concurrency Standards - async/await, Future, Stream, Isolates
3. Type Safety Standards - Null safety, sealed classes, records (Dart 3.0+)
4. Performance Standards - const constructors, lazy init, Isolates
5. Security Standards - Input validation, secure storage
6. API Standards - shelf HTTP patterns, REST conventions
7. DDD Standards - Domain-Driven Design patterns
8. Framework Integration - Flutter, Riverpod, shelf

Related Skills

• docs-applying-content-quality
• repo-practicing-trunk-based-development

References

• Dart README
• Functional Programming