Code Review Reference Guide#

Detailed checklists and review criteria by category.

1. Architecture#

Clean Architecture Review#

Feature Module Independence#

// ✅ Correct dependency
import 'package:core/core.dart';
import 'package:feature_common_auth/auth.dart';

// ❌ Incorrect dependency (direct reference to another application feature)
import 'package:feature_application_home/home.dart';

Checklist#

• Domain → Data → Presentation dependency direction followed
• Business logic accessed through UseCases
• Repository interface separation (I prefix)
• No direct dependencies between feature modules
• Shared code separated into common or core
• No over-abstraction

2. State Management#

BLoC Pattern Review#

State Definition Pattern#

// ✅ Correct state definition
@freezed
class HomeState with _$HomeState {
  const factory HomeState.initial() = _Initial;
  const factory HomeState.loading() = _Loading;
  const factory HomeState.loaded(User user) = _Loaded;
  const factory HomeState.error(Failure failure) = _Error;
}

// ❌ Incorrect state definition (not using Freezed)
class HomeState {
  final bool isLoading;
  final User? user;
  final String? error;
}

Checklist#

• Freezed used for Event/State
• State branching with Union Types
• Proper error handling
• Loading state management
• Resources released in dispose
• Global/local state properly distinguished

3. Security#

Sensitive Information Review#

Input Validation#

// ✅ Correct validation
if (!EmailValidator.validate(email)) {
  return left(ValidationFailure('Invalid email'));
}

// ❌ Direct use without validation
final user = await api.login(email, password);

Checklist#

• No hardcoded API keys or secrets
• No sensitive information in logs
• User input sanitization
• SQL Injection, XSS prevention
• Protected endpoint access control
• Proper token management

4. Performance#

Rebuild Optimization#

Image Optimization#

// ✅ Correct image handling
CachedNetworkImage(
  imageUrl: url,
  cacheWidth: 200,
  cacheHeight: 200,
)

// ❌ Cache size not specified
Image.network(url)

Checklist#

• const widgets utilized
• BlocBuilder buildWhen used
• Refined with BlocSelector
• Image cacheWidth/cacheHeight applied
• Parallelizable tasks parallelized
• debounce/throttle applied
• Resources released in dispose
• Stream subscriptions cancelled

5. Testing#

Test Coverage#

Test Pattern#

// ✅ Correct test pattern (AAA)
test('should return user when repository succeeds', () async {
  // Arrange
  when(() => mockRepository.getUser(any()))
    .thenAnswer((_) async => Right(testUser));

  // Act
  final result = await useCase(GetUserParams(id: 1));

  // Assert
  expect(result, Right(testUser));
  verify(() => mockRepository.getUser(1)).called(1);
});

Checklist#

• UseCase unit tests
• Repository tests (mocked)
• BLoC tests
• Meaningful test cases
• Edge cases covered
• Arrange-Act-Assert pattern
• External dependencies isolated

6. Readability#

Naming Convention#

Code Structure#

// ✅ Single Responsibility Principle
class UserRepository implements IUserRepository {
  // User-related logic only
}

// ❌ Multiple responsibilities mixed
class UserRepository {
  void getUser() {}
  void sendEmail() {}  // Email should be a separate service
  void generateReport() {}  // Report should be separate too
}

Checklist#

• Clear and meaningful names
• Project convention followed
• Abbreviation usage minimized
• Appropriate file/class size
• Single Responsibility Principle
• Duplicate code removed
• No unnecessary comments
• Explanatory comments on complex logic

7. Internationalization (i18n)#

Translation Key Usage#

// ✅ Correct usage
Text(context.t.common.save)
Text(context.t.user.greeting(name: user.name))

// ❌ Hardcoded
Text('Save')
Text('Hello, ${user.name}!')

Checklist#

• All UI text uses translation keys
• context.t.* pattern used
• Proper pluralization
• Dynamic values parameterized
• RTL support (if needed)

8. Accessibility#

Semantics Applied#

// ✅ Correct application
Semantics(
  label: 'Add to cart',
  button: true,
  child: IconButton(
    icon: Icon(Icons.add_shopping_cart),
    onPressed: addToCart,
  ),
)

// ❌ No Semantics
IconButton(
  icon: Icon(Icons.add_shopping_cart),
  onPressed: addToCart,
)

Checklist#

• Appropriate semantic labels
• Screen reader support
• Minimum 48x48 touch target
• WCAG color contrast criteria met
• Information not conveyed by color alone

Automation Tools#

Static Analysis#

# Full analysis
melos run analyze

# Parallel lint
melos run lint:parallel

# Formatting check
melos run format
dart format --set-exit-if-changed .

Testing#

# Full test suite
melos run test

# Coverage report
melos run test:with-html-coverage