coding-standards

name	coding-standards
description	Verify that all code changes adhere to the professor's grading criteria and Aptis App coding standards.

Coding and Grading Standards Skill

Use this skill to ensure all code changes comply with the project's coding standards and professor's grading guidelines.

When to use this skill

• Use this skill before implementing any new features or modifying existing code in this repository.
• Use this skill to check code formatting, widget decomposition rules, state management rules (BLoC/Cubit), async safety, and resource lifecycle compliance before completing a task.

Key Guidelines

1. Grading Standards

The grading standards are located at flutter-grading-standards.md. Key Rules:

• Project Structure: Clean & Modular under features/ (Clean Architecture). Never put business logic/API calls in main.dart.
• Readable Code: Names must be descriptive; use helper methods for methods > 60 lines.
• Widget Decomposition: build() method must not exceed ~50 lines. Extract sub-widgets.
• Logic Separated from UI: Event handlers must not contain inline API calls/validation/navigation.
• State Management: App-wide/feature-level state must use BLoC/Cubit. Ephemeral state can use setState.
• Navigation: Centrally defined routing (app_router.dart or equivalent). No hard-coded route strings in screens.
• Data Modeling: Use typed classes (not Map or dynamic).
• Error Handling: Wrapped async calls in try/catch or use Result<T>. Validate all form inputs.
• Responsive UI: Wrap scrollables in SingleChildScrollView or ListView. SafeAreas for top-level screens. Zero tolerance for overflow errors.
• Code Reuse & Constants: Define colors, route names, dimensions, and user-facing strings in core/constants/. All user-facing strings must be i18n-ready via AppStrings.
• Performance: Use ListView.builder(), const constructors, cached network images.

2. Coding Standards

The full coding standards are located at CODING_STANDARDS_APP.md. Key Rules:

• Naming Conventions:
  • File: snake_case.dart (e.g. exam_started_event.dart, exam_card_widget.dart)
  • Class: PascalCase (e.g. ExamAttemptBloc, ExamLoadingState)
  • Method/Variable: camelCase (e.g. loadExamDetails(), isLoading)
  • Constant: lowerCamelCase const (e.g. const String examNotFound = '...', not EXAM_NOT_FOUND)
  • Private member: _prefix (e.g. _examRepository, _loadExamDetails)
• File size limits: Max 300 lines per file (excluding autogenerated code).
• Dependency Injection: Via GetIt inside features' module files (e.g. exam_module.dart).
• Async Safety:
  • Always check if (!mounted) return; after await and before using BuildContext (e.g., popped widget scenario).
  • BLoC must not import package:flutter/material.dart and must not use BuildContext (use States to notify the UI).
• Resource Lifecycle: Overriding dispose() is mandatory for all controllers, subscriptions, and timers.

Verification Checklist

Always run the following verification steps before finalizing your changes:

1. Run dart analyze to ensure zero errors and zero warnings.
2. Run dart format . to format the workspace.
3. Review your diff against the Code Review Checklist in CODING_STANDARDS_APP.md.