Android Development Standards

These standards apply to all Android application code unless a specific project document explicitly says otherwise. When in doubt, follow these conventions.

1. Technology and language

• Prefer Kotlin for all new Android code.
• Use Jetpack Compose for UI in new features. Use XML layouts only when:
  • Modifying existing XML based screens.
  • Integrating legacy components that are not Compose ready.
• Use Android Jetpack libraries where appropriate:
  • ViewModel, LiveData or StateFlow, Navigation, Room, DataStore, WorkManager.

When a module is already heavily based on Java or XML, follow the existing style in that module and avoid mixing paradigms without a clear and incremental migration plan.

2. Architecture

Follow clean architecture with clear separation of concerns.

• Use MVVM as the default presentation pattern.
• Structure code into layers:
  • presentation for UI and ViewModels.
  • domain for use cases and business logic.
  • data for repositories and data sources.
• ViewModels:
  • Expose UI state via StateFlow, SharedFlow or MutableState for Compose.
  • Keep Android framework types out of the domain layer.
• Repositories:
  • Hide data source and caching details from the rest of the app.
  • Expose suspend functions or reactive streams for consumption.

3. Project structure

Prefer a modular structure in larger apps.

• Split into modules such as:
  • core for shared utilities, design system, common models.
  • feature-* modules per screen or feature.
  • data-* modules per data source when complex enough.
• Avoid creating new modules for trivial features. Default to placing code in existing relevant modules.

Use consistent and meaningful package names:

• com.company.app.feature.name
• com.company.app.core.ui
• com.company.app.data.api

4. UI and Compose standards

• Maintain a single source of truth for UI state per screen.
• Write composable functions that:
  • Are small, focused and composable.
  • Receive all dynamic data and callbacks via parameters.
  • Do not access repositories, data sources or navigation directly.
• Use a central design system:
  • Centralise colours, typography, shapes and spacing in a designsystem or core/ui module.
  • Avoid hard coded values in composables. Use theme tokens instead.
• Model screen states explicitly, for example:
  • Loading
  • Content
  • Empty
  • Error
• Accessibility:
  • Provide contentDescription for important images and icons.
  • Ensure tap targets are large enough and layouts support dynamic font sizes.

5. Navigation

• Use the Navigation Component or Compose Navigation for in app navigation.
• Define routes or destinations in a single place per feature.
• Pass only minimal arguments between screens. Prefer IDs over full objects.
• Do not store NavController in ViewModels. Pass it from composables or use navigation events from ViewModels that are handled in the UI layer.

6. Data, networking and persistence

• Use a dedicated networking layer:
  • Prefer Retrofit with OkHttp for HTTP APIs when suitable.
  • Model responses with data classes and map them into domain models.
• Error handling:
  • Wrap remote calls in a result type, such as Result<T> or a sealed class.
  • Distinguish clearly between:
    • Network errors.
    • Server errors.
    • Business rule or validation errors.
• Persistence:
  • Use Room for structured data and DataStore for key value preferences.
  • Keep database entities separate from domain models. Map explicitly between layers.
• Do not block the main thread:
  • Use coroutines with Dispatchers.IO for IO and heavy work.
  • Ensure any expensive computation runs off the UI thread.

7. Dependency injection

• Use Hilt as the default dependency injection framework in new projects.
• Provide Hilt modules for:
  • Network clients.
  • Repositories.
  • Use cases and other core services.
• Do not manually construct dependencies inside ViewModels or composables.

8. Coroutines and concurrency

• Use structured concurrency:
  • Launch coroutines in appropriate scopes such as viewModelScope or lifecycleScope.
  • Ensure work is cancelled when the owning scope is cancelled.
• Use suspend functions for long running or IO operations.
• Avoid GlobalScope except for initialisation that must live for the entire process lifetime and is explicitly safe.

9. Testing

• Types of tests:
  • Unit tests for ViewModels, use cases and pure logic.
  • Instrumentation tests for persistence and integration with Android components.
  • UI tests using Compose testing APIs, or Espresso for legacy views.
• Testing rules:
  • Cover new ViewModel and use case logic with tests.
  • Mock external dependencies instead of calling real services.
  • Keep tests deterministic, isolated and fast.

10. Performance and reliability

• Avoid unnecessary recompositions in Compose:
  • Hoist state where possible and use stable data structures.
  • Use remember only where it avoids work and does not hide state.
• Use pagination for lists that can grow large.
• Use WorkManager for background work that must be guaranteed or persisted.
• Monitor startup time and memory usage. When optimisation is needed, measure first, then change code based on data.

11. Security and privacy

• Do not store secrets in source code or in the app binary.
• Use secure storage for sensitive user data according to platform guidance.
• Follow platform recommendations for permissions:
  • Request permissions as late as possible, near the feature that needs them.
  • Provide rationale dialogs when appropriate.
• When handling personal data, adhere to project specific privacy, compliance and regulatory requirements.

12. AI coding agent guidance

When acting as an AI coding agent on Android tasks:

• Respect existing project patterns and constraints before introducing new libraries or frameworks.
• When adding dependencies:
  • Justify why they are needed.
  • Update relevant Gradle files consistently, including version catalogues if present.
• Prefer small, incremental changes over large refactors. Preserve behaviour unless a change is explicitly requested.
• Clearly explain:
  • Breaking changes.
  • Migration steps.
  • Any required manual changes or configuration updates for the team.