# Core Architecture Standards for Kotlin Android
This document outlines the core architectural standards for Kotlin Android development. It aims to guide developers in creating maintainable, scalable, and robust applications by establishing best practices for project structure, architectural patterns, and organization principles.
## 1. Architectural Patterns
Choosing the right architectural pattern is crucial for structuring your Android application. This section outlines the recommended architectural patterns and their implementation in Kotlin.
### 1.1 Recommended Architecture: MVVM (Model-View-ViewModel)
MVVM is the recommended architectural pattern for Kotlin Android applications due to its clear separation of concerns, testability, and maintainability. It separates the UI (View), the data (Model), and the logic that connects them (ViewModel).
**Do This:**
* Employ MVVM architecture for all new Android projects and refactor existing projects to adopt MVVM where feasible.
* Ensure a clear separation between the View (Activities/Fragments), ViewModel, and Model layers.
* Use data binding to connect the View and ViewModel, reducing boilerplate code.
* Employ unidirectional Data Flow
**Don't Do This:**
* Directly manipulate the UI from the Model layer.
* Place business logic within Activities or Fragments.
* Treat Activities/Fragments as more than just UI controllers.
**Why This Matters:**
MVVM enhances code maintainability, testability (ViewModels can be easily unit-tested), and reusability. It also facilitates parallel development by separating UI design from business logic implementation.
**Code Example:**
"""kotlin
// Model: Data class representing a user
data class User(val name: String, val age: Int)
// ViewModel: Exposes user data to the View and handles user interactions
class UserViewModel : ViewModel() {
private val _user = MutableLiveData()
val user: LiveData = _user
init {
// Initialize with some data
_user.value = User("John Doe", 30)
}
fun updateUser(name: String, age: Int) {
_user.value = User(name, age)
}
}
// View: Activity or Fragment observes the ViewModel and updates the UI
class UserActivity : AppCompatActivity() {
private lateinit var binding: ActivityUserBinding
private val userViewModel: UserViewModel by viewModels()
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
binding = ActivityUserBinding.inflate(layoutInflater)
setContentView(binding.root)
userViewModel.user.observe(this) { user ->
binding.nameTextView.text = user.name
binding.ageTextView.text = user.age.toString()
}
binding.updateButton.setOnClickListener {
userViewModel.updateUser("Jane Doe", 25)
}
}
}
// activity_user.xml
"""
**Anti-Pattern:** Placing business logic directly inside the activity.
"""kotlin
// Anti-pattern: Business logic in activity
class BadUserActivity : AppCompatActivity() {
private lateinit var binding: ActivityUserBinding
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
binding = ActivityUserBinding.inflate(layoutInflater)
setContentView(binding.root)
binding.updateButton.setOnClickListener {
// Directly manipulating UI and data here - BAD!
binding.nameTextView.text = "Jane Doe"
binding.ageTextView.text = "25"
}
}
}
"""
### 1.2 Alternatives: MVI (Model-View-Intent)
MVI is another architecture, especially suitable when complex state management is needed but the complexity added warrants its use.
**Do This:**
* Embrace unidirectional data flow: "View -> Intent -> Model -> State -> View"
* Implement immutable state
* Use Kotlin coroutines or RxJava for handling asynchronous operations and state updates
**Don't Do This:**
* Mutate the state directly; always create a new state object.
* Overcomplicate simple applications with MVI where MVVM suffice
**Why This Matters:**
MVI offers predictable state management, ease of debugging, and better testability. The unidirectional flow makes it easy to track changes and understand application behavior.
**Code Example:**
"""kotlin
// Data classes for State, Intent, and Result
data class UserState(val name: String = "", val age: Int = 0)
sealed class UserIntent {
data class UpdateName(val name: String) : UserIntent()
data class UpdateAge(val age: Int) : UserIntent()
}
sealed class UserResult {
data class NameUpdated(val name: String) : UserResult()
data class AgeUpdated(val age: Int) : UserResult()
}
// ViewModel acting as the "Controller"
class UserViewModel : ViewModel() {
private val _state = MutableStateFlow(UserState())
val state: StateFlow = _state.asStateFlow()
fun processIntent(intent: UserIntent) {
when (intent) {
is UserIntent.UpdateName -> updateName(intent.name)
is UserIntent.UpdateAge -> updateAge(intent.age)
}
}
private fun updateName(name: String) {
_state.value = _state.value.copy(name = name)
}
private fun updateAge(age: Int) {
_state.value = _state.value.copy(age = age)
}
}
// View (Activity/Fragment)
class UserActivity : AppCompatActivity() {
private lateinit var binding: ActivityUserBinding
private val userViewModel: UserViewModel by viewModels()
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
binding = ActivityUserBinding.inflate(layoutInflater)
setContentView(binding.root)
lifecycleScope.launch {
userViewModel.state.collect { state ->
binding.nameTextView.text = state.name
binding.ageTextView.text = state.age.toString()
}
}
binding.updateNameButton.setOnClickListener {
userViewModel.processIntent(UserIntent.UpdateName("Jane Doe"))
}
binding.updateAgeButton.setOnClickListener {
userViewModel.processIntent(UserIntent.UpdateAge(25))
}
}
}
"""
### 1.3 Alternatives: Clean Architecture
Clean Architecture is a software design philosophy. It's mostly platform agnostic but can be adapted to Android development. The idea is to isolate the business rules, making the system easier to test, maintain, and extend.
**Do This:**
* Separate entities, use cases, interface adapters, and frameworks/drivers.
* Define clear boundaries between layers using interfaces.
* Make dependency flow towards the entities (business logic).
**Don't Do This:**
* Allow UI concerns to dictate business logic.
* Tightly couple your business logic to Android framework components.
**Why This Matters:**
Clean Architecture focuses on isolating core business logic enabling independent evolution of core application logic from UI and data layer. This provides scalability and maintainability, even as underlying frameworks change over time.
**Code Example:**
"""kotlin
// Entity Layer
data class Product(val id: Int, val name: String, val price: Double)
// Use Case Layer (Interactor)
class GetProductUseCase(private val productRepository: ProductRepository) {
suspend fun execute(productId: Int): Product {
return productRepository.getProduct(productId)
}
}
// Interface Adapters Layer (Repository Interface)
interface ProductRepository {
suspend fun getProduct(productId: Int): Product
}
// Frameworks & Drivers Layer (Repository Implementation)
class ProductRepositoryImpl(private val productApi: ProductApi) : ProductRepository {
override suspend fun getProduct(productId: Int): Product {
// Implementation using Retrofit, for example
return productApi.getProduct(productId)
}
}
// API Interface (using Retrofit)
interface ProductApi {
@GET("products/{id}")
suspend fun getProduct(@Path("id") productId: Int): Product
}
// ViewModel using the Use Case
class ProductViewModel(private val getProductUseCase: GetProductUseCase) : ViewModel() {
private val _product = MutableLiveData()
val product: LiveData = _product
fun fetchProduct(productId: Int) {
viewModelScope.launch {
try {
_product.value = getProductUseCase.execute(productId)
} catch (e: Exception) {
// Handle error
}
}
}
}
"""
## 2. Project Structure
A well-defined project structure is essential for code organization and maintainability.
### 2.1 Package Structure
**Do This:**
* Organize your code into feature-based packages. For example, "com.example.app.feature_name".
* Create separate packages for models, views, viewmodels, repositories, and utilities.
* Use "internal" visibility modifier wherever possible to limit access to classes/functions in a package
**Don't Do This:**
* Place all classes in a single package.
* Mix UI-related components with business logic in the same package.
**Why This Matters:**
A clear package structure promotes code discoverability, reduces dependencies, and improves maintainability. It allows developers to quickly locate and understand different parts of the application.
**Code Example:**
"""
com.example.app
├── feature_auth
│ ├── ui
│ │ ├── AuthActivity.kt
│ │ └── AuthViewModel.kt
│ ├── data
│ │ ├── AuthRepository.kt
│ │ └── AuthApiService.kt
│ └── model
│ └── User.kt
├── feature_home
│ ├── ui
│ │ ├── HomeActivity.kt
│ │ └── HomeViewModel.kt
│ ├── data
│ │ ├── HomeRepository.kt
│ │ └── HomeApiService.kt
│ └── model
│ └── Article.kt
├── di
│ └── AppModule.kt
└── util
└── NetworkUtils.kt
"""
### 2.2 Module Structure
For larger applications, consider using a modular architecture. Modularization is a development practice that involves dividing an application into smaller, independent modules that can be developed, tested, and deployed separately. This enhances code reusability, improves build times, and supports parallel development efforts.
**Do This:**
* Divide your application into modules based on features or functionalities.
* Define clear module dependencies.
* Each module should be independently testable
* Create "api" and "implementation" configurations in each module's "build.gradle.kts". Anything exposed in "api" is accessible to external modules, "implementation" is not.
Implementation details should be behind interfaces.
**Don't Do This:**
* Create circular module dependencies.
* Over-modularize small applications, adding unnecessary complexity.
* Include implementation details in API modules
**Why This Matters:**
Modularization improves build times, enhances code reusability, and supports parallel development efforts. Modules can be independently tested and deployed, minimizing the impact of changes.
**Code Example:**
In "settings.gradle.kts":
"""kotlin
include(":app")
include(":feature_auth")
include(":feature_home")
include(":core") // Core functionalities
"""
In "feature_auth/build.gradle.kts":
"""kotlin
dependencies {
implementation(project(":core"))
// Other dependencies
}
"""
In "feature_home/build.gradle.kts":
"""kotlin
dependencies {
implementation(project(":core"))
implementation(project(":feature_auth")) //Can depend on other feature modules
// Other dependencies
}
"""
## 3. Data Management
Efficiently managing data is crucial for Android applications.
### 3.1 Repository Pattern
**Do This:**
* Implement a repository layer to abstract data sources (local database, network API, etc.).
* Use Kotlin Coroutines or RxJava for handling asynchronous operations in the repository. Expose Flow or LiveData to ViewModel
**Don't Do This:**
* Directly access data sources from ViewModels or UI components.
* Mix data retrieval logic with business logic.
**Why This Matters:**
The repository pattern decouples data access logic from the rest of the application, making it easier to switch between data sources or implement caching strategies.
**Code Example:**
"""kotlin
// Data source interface
interface UserDataSource {
suspend fun getUser(userId: Int): User
}
// Remote data source (e.g., using Retrofit)
class RemoteUserDataSource(private val apiService: UserApiService) : UserDataSource {
override suspend fun getUser(userId: Int): User {
return apiService.getUser(userId)
}
}
// Local data source (e.g., using Room)
class LocalUserDataSource(private val userDao: UserDao) : UserDataSource {
override suspend fun getUser(userId: Int): User {
return userDao.getUser(userId)
}
}
// Repository implementation
class UserRepository(
private val remoteDataSource: RemoteUserDataSource,
private val localDataSource: LocalUserDataSource
) {
suspend fun getUser(userId: Int): User {
// Implement caching strategy here
try {
val user = remoteDataSource.getUser(userId)
localDataSource.userDao.insert(user) // Save to local DB
return user
} catch (e: Exception) {
// If network fails, get from local DB
return localDataSource.getUser(userId) ?: throw e
}
}
}
"""
### 3.2 Room Persistence Library
**Do This:**
* Use Room for local data persistence.
* Define clear data entities, DAOs, and database classes.
* Use Kotlin Coroutines for performing database operations asynchronously.
* Implement migrations to handle schema changes with database versions
**Don't Do This:**
* Perform database operations on the main thread.
* Store sensitive data in plain text.
**Why This Matters:**
Room provides a robust and type-safe way to interact with SQLite databases. It simplifies database management and reduces boilerplate code.
**Code Example:**
"""kotlin
// Entity
@Entity(tableName = "users")
data class User(
@PrimaryKey val id: Int,
val name: String,
val email: String
)
// DAO (Data Access Object)
@Dao
interface UserDao {
@Query("SELECT * FROM users WHERE id = :userId")
suspend fun getUser(userId: Int): User?
@Insert(onConflict = OnConflictStrategy.REPLACE)
suspend fun insert(user: User)
}
// Database
@Database(entities = [User::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
abstract fun userDao(): UserDao
companion object {
@Volatile
private var INSTANCE: AppDatabase? = null
fun getDatabase(context: Context): AppDatabase {
return INSTANCE ?: synchronized(this) {
val instance = Room.databaseBuilder(
context.applicationContext,
AppDatabase::class.java,
"app_database"
).build()
INSTANCE = instance
instance
}
}
}
}
"""
## 4. Asynchronous Operations
Handling asynchronous operations correctly is vital for maintaining UI responsiveness and preventing ANR (Application Not Responding) errors.
### 4.1 Kotlin Coroutines
**Do This:**
* Use Kotlin Coroutines for asynchronous programming.
* Use "viewModelScope" (or "lifecycleScope" where appropriate) for launching coroutines in ViewModels.
* Handle exceptions properly within coroutines using "try-catch" blocks or "CoroutineExceptionHandler".
**Don't Do This:**
* Block the main thread with long-running operations.
* Forget to cancel coroutines when they are no longer needed.
* Ignore exceptions within coroutines.
**Why This Matters:**
Kotlin Coroutines provide a lightweight and efficient way to handle asynchronous tasks. They simplify asynchronous code and make it more readable.
**Code Example:**
"""kotlin
class MyViewModel : ViewModel() {
private val _data = MutableLiveData()
val data: LiveData = _data
fun fetchData() {
viewModelScope.launch {
try {
val result = withContext(Dispatchers.IO) {
// Simulate a network call
delay(1000)
"Data from network"
}
_data.value = result
} catch (e: Exception) {
// Handle error
Log.e("MyViewModel", "Error fetching data", e)
}
}
}
override fun onCleared() {
super.onCleared()
// Coroutines are automatically cancelled when the ViewModel is destroyed.
}
}
"""
### 4.2 Flow
**Do This:**
* Use "Flow" for asynchronous streams of data.
* Use operators to transform and filter data.
* Collect "Flow" data in UI using "collectAsState" (in Jetpack Compose) or "observe" (in Activities/Fragments).
**Don't Do This:**
* Create infinite loops with "Flow".
* Neglect error handling within your flows
**Why This Matters:**
Flow provides a reactive way to handle asynchronous data streams. It offers powerful operators for data transformation and composition.
**Code Example:**
"""kotlin
class MyViewModel : ViewModel() {
private val _data = MutableStateFlow("")
val data: StateFlow = _data.asStateFlow()
init {
viewModelScope.launch {
try {
flow {
emit("Initial Data")
delay(500)
emit("Fetching...")
delay(1000)
emit("Data from Flow!")
}
.collect { result ->
_data.value = result
}
} catch (e: Exception) {
Log.e("MyViewModel", "Error with flow", e)
}
}
}
}
"""
## 5. Dependency Injection
Dependency injection (DI) is a design pattern that allows you to develop loosely coupled code. Libraries like Hilt and Koin are often utilized for DI in Kotlin Android projects.
### 5.1 Hilt
**Do This:**
* Use Hilt for dependency injection in Android applications.
* Annotate classes with "@AndroidEntryPoint" for injection in Activities/Fragments.
* Use "@InstallIn" to specify the scope of dependencies.
* Use Qualifiers like "@Named" or create your own to differentiate between multiple dependencies of the same type
**Don't Do This:**
* Manually create and manage dependencies in your classes.
* Overuse "@Singleton" scope, as this can lead to memory leaks and performance issues.
**Why This Matters:**
Hilt simplifies DI in Android by providing a standard way to manage dependencies. It reduces boilerplate code and improves testability.
**Code Example:**
"""kotlin
@Module
@InstallIn(SingletonComponent::class)
object AppModule {
@Provides
@Singleton
fun provideApiService(): ApiService {
return Retrofit.Builder()
.baseUrl("https://api.example.com/")
.addConverterFactory(GsonConverterFactory.create())
.build()
.create(ApiService::class.java)
}
@Provides
fun provideUserRepository(apiService: ApiService): UserRepository {
return UserRepositoryImpl(apiService)
}
}
@AndroidEntryPoint
class MyActivity : AppCompatActivity() {
@Inject
lateinit var userRepository: UserRepository
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Use userRepository here
}
}
"""
### 5.2 Koin (Alternative)
Koin is a lightweight dependency injection framework for Kotlin
**Do This:**
* Define modules using "module {}" and declare dependencies using "single", "factory", or "viewModel".
* Inject dependencies using "by inject()" in your classes.
* In "Application" class, start Koin using "startKoin { modules(...) }"
**Don't Do This:**
* Overuse global state making testing more difficult.
* Mix creation and injection logic within the same classes.
**Why This Matters:**
Koin reduces boilerplate code associated with dependency injection, facilitating clearer and more concise dependency management.
**Code Example:**
"""kotlin
val appModule = module {
single { ApiService() } // Define a singleton
factory { UserRepository(get()) } // Define a new instance each time
viewModel { MyViewModel(get()) } // Declare a ViewModel
}
class MyViewModel(private val userRepository: UserRepository) : ViewModel() {
// ...
}
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
startKoin {
androidContext(this@MyApplication)
modules(appModule)
}
}
}
class MyActivity : AppCompatActivity() {
private val myViewModel: MyViewModel by viewModel()
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// ...
}
}
"""
## 6. Testing
Writing automated tests is essential for ensuring the quality and reliability of your application.
### 6.1 Unit Tests
**Do This:**
* Write unit tests for ViewModels, repositories, and utility classes.
* Use mocking frameworks like Mockito or MockK to isolate units of code.
* Follow the AAA (Arrange, Act, Assert) pattern for structuring tests.
**Don't Do This:**
* Skip unit tests for critical components.
* Write tests that are tightly coupled to implementation details.
* Write tests that require a running emulator/device
**Why This Matters:**
Unit tests verify the correctness of individual units of code. They help catch bugs early and ensure that changes do not break existing functionality.
**Code Example:**
"""kotlin
@Test
fun "fetchData should update data LiveData with result"() = runBlocking {
// Arrange
val mockRepository = mockk()
val expectedResult = "Test Data"
coEvery { mockRepository.getData() } returns expectedResult
val viewModel = MyViewModel(mockRepository)
// Act
viewModel.fetchData()
delay(100) // Give time for coroutine to execute
// Assert
assertEquals(expectedResult, viewModel.data.getOrAwaitValue())
}
"""
### 6.2 UI Tests
**Do This:**
* Write UI tests to verify user interactions and UI behavior.
* Use Espresso for writing instrumented UI tests.
* Use UI Automator for testing across multiple apps.
**Don't Do This:**
* Write flaky or unreliable UI tests.
* Test implementation details in UI tests.
**Why This Matters:**
UI tests verify that the UI behaves as expected and that user interactions are handled correctly. They help catch UI-related bugs and ensure a good user experience.
## 7. Code formatting and linting
Maintaining a consistent code style throughout the project makes the code readable and easier to contribute to.
### 7.1. Kotlin Style Guide
**Do This:**
* Adhere to the official [Kotlin style guide](https://kotlinlang.org/docs/coding-conventions.html) and [Android Kotlin Style Guide](https://developer.android.com/kotlin/style-guide).
* Use ".editorconfig" files to enforce consistent code style in your IDE
* Use detekt for static code analysis
* Configure Android Studio code style settings as per the Kotlin style guide.
**Don't Do This:**
* Ignore code formatting issues.
* Commit code with inconsistent styling.
## 8. Security
Security considerations are crucial for Android development to protect user data and prevent vulnerabilities.
### 8.1 Data Encryption
**Do This:**
* Encrypt sensitive data stored locally using the Android Keystore system.
* Use HTTPS for network communication.
* Validate user input to prevent injection attacks.
**Don't Do This:**
* Store passwords or API keys in plain text.
* Trust user input without validation.
### 8.2 Permissions
**Do This:**
* Request only necessary permissions.
* Explain why each permission is needed to the user.
* Handle permission requests gracefully.
**Don't Do This:**
* Request excessive permissions.
* Assume permissions are granted without checking.
## 9. Summary
Following these core architecture standards will result in Kotlin Android applications that are well-structured, maintainable, testable, and secure. Remember to regularly review and update these standards as the Kotlin and Android ecosystems evolve.
danielsogl
Created Mar 6, 2025
This guide explains how to effectively use .clinerules with Cline, the AI-powered coding assistant.
The .clinerules file is a powerful configuration file that helps Cline understand your project's requirements, coding standards, and constraints. When placed in your project's root directory, it automatically guides Cline's behavior and ensures consistency across your codebase.
Place the .clinerules file in your project's root directory. Cline automatically detects and follows these rules for all files within the project.
# Project Overview project: name: 'Your Project Name' description: 'Brief project description' stack: - technology: 'Framework/Language' version: 'X.Y.Z' - technology: 'Database' version: 'X.Y.Z'
# Code Standards standards: style: - 'Use consistent indentation (2 spaces)' - 'Follow language-specific naming conventions' documentation: - 'Include JSDoc comments for all functions' - 'Maintain up-to-date README files' testing: - 'Write unit tests for all new features' - 'Maintain minimum 80% code coverage'
# Security Guidelines security: authentication: - 'Implement proper token validation' - 'Use environment variables for secrets' dataProtection: - 'Sanitize all user inputs' - 'Implement proper error handling'
Be Specific
Maintain Organization
Regular Updates
# Common Patterns Example patterns: components: - pattern: 'Use functional components by default' - pattern: 'Implement error boundaries for component trees' stateManagement: - pattern: 'Use React Query for server state' - pattern: 'Implement proper loading states'
Commit the Rules
.clinerules in version controlTeam Collaboration
Rules Not Being Applied
Conflicting Rules
Performance Considerations
# Basic .clinerules Example project: name: 'Web Application' type: 'Next.js Frontend' standards: - 'Use TypeScript for all new code' - 'Follow React best practices' - 'Implement proper error handling' testing: unit: - 'Jest for unit tests' - 'React Testing Library for components' e2e: - 'Cypress for end-to-end testing' documentation: required: - 'README.md in each major directory' - 'JSDoc comments for public APIs' - 'Changelog updates for all changes'
# Advanced .clinerules Example project: name: 'Enterprise Application' compliance: - 'GDPR requirements' - 'WCAG 2.1 AA accessibility' architecture: patterns: - 'Clean Architecture principles' - 'Domain-Driven Design concepts' security: requirements: - 'OAuth 2.0 authentication' - 'Rate limiting on all APIs' - 'Input validation with Zod'
# Tooling and Ecosystem Standards for Kotlin Android This document outlines coding standards focusing specifically on tooling and ecosystem-related best practices for Kotlin Android development. Following these standards ensures maintainable, performant, and secure applications built with the latest Kotlin Android features. ## 1. Dependency Management ### 1.1. Standard Utilize Gradle Kotlin DSL (build.gradle.kts) for dependency management. Leverage semantic versioning and Kotlin's type-safe accessors for dependencies. **Do This:** """kotlin // build.gradle.kts plugins { id("com.android.application") id("org.jetbrains.kotlin.android") id("kotlin-kapt") // For annotation processing (e.g., Dagger/Hilt) } android { namespace = "com.example.myapp" compileSdk = 34 defaultConfig { applicationId = "com.example.myapp" minSdk = 24 targetSdk = 34 versionCode = 1 versionName = "1.0" testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner" } buildTypes { release { isMinifyEnabled = true proguardFiles( getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro" ) } debug { // Debug-specific configurations go here } } compileOptions { sourceCompatibility = JavaVersion.VERSION_17 // Or a later version targetCompatibility = JavaVersion.VERSION_17 } kotlinOptions { jvmTarget = "17" } buildFeatures { viewBinding = true // Enable View Binding dataBinding = false // Explicitly disable Data Binding if not used } } dependencies { implementation("androidx.core:core-ktx:1.12.0") implementation("androidx.appcompat:appcompat:1.6.1") implementation("com.google.android.material:material:1.12.0-alpha04") implementation("androidx.constraintlayout:constraintlayout:2.1.4") testImplementation("junit:junit:4.13.2") androidTestImplementation("androidx.test.ext:junit:1.1.5") androidTestImplementation("androidx.test.espresso:espresso-core:3.5.1") // Kotlin Coroutines implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3") // Retrofit for networking implementation("com.squareup.retrofit2:retrofit:2.11.0") implementation("com.squareup.retrofit2:converter-gson:2.11.0") // Dagger/Hilt for Dependency Injection implementation("com.google.dagger:hilt-android:2.51") kapt("com.google.dagger:hilt-compiler:2.51") // Lifecycle components implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.8.0-alpha01") implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.8.0-alpha01") implementation("androidx.lifecycle:lifecycle-livedata-ktx:2.8.0-alpha01") // Timber for logging implementation("com.jakewharton.timber:timber:5.0.1") // Coil for image loading implementation("io.coil-kt:coil:2.6.0") // Room Persistence Library implementation("androidx.room:room-runtime:2.7.0") kapt("androidx.room:room-compiler:2.7.0") implementation("androidx.room:room-ktx:2.7.0") // Kotlin coroutine support for Room // Navigation Component implementation("androidx.navigation:navigation-fragment-ktx:2.7.7") implementation("androidx.navigation:navigation-ui-ktx:2.7.7") } """ **Don't Do This:** * Using the Groovy DSL ("build.gradle") for new projects. Kotlin DSL offers type safety and better IDE support. * Hardcoding dependency versions directly without using variables or dependency catalogs where possible. * Ignoring dependency updates. Regularly check for newer versions to benefit from bug fixes and performance improvements. **Why:** * **Maintainability:** Centralized dependency management simplifies version updates and ensures consistency across modules. * **Type Safety:** Kotlin DSL provides compile-time checking of dependencies, reducing runtime errors. * **Organization:** Well-structured "build.gradle.kts" files improve readability and ease collaboration. **Anti-pattern:** * Having inconsistent dependency versions across different modules. * Using a very old version of a support library without a valid reason. **Specific Notes for Kotlin Android:** Leverage Kotlin extensions (ktx) for Android libraries. For example, using "androidx.core:core-ktx" provides extension functions that make working with Android APIs more concise and Kotlin-friendly. ### 1.2. Dependency Catalogs Adopt dependency catalogs with TOML files to centralize and manage dependencies across multiple modules in larger projects. **Do This:** * Create a "libs.versions.toml" file in the "gradle" directory of your project. """toml # libs.versions.toml [versions] kotlin = "1.9.23" appcompat = "1.6.1" material = "1.12.0-alpha04" coroutines = "1.7.3" retrofit = "2.11.0" dagger = "2.51" lifecycle = "2.8.0-alpha01" room = "2.7.0" [libraries] androidx-core-ktx = { module = "androidx.core:core-ktx", version = "1.12.0" } androidx-appcompat = { module = "androidx.appcompat:appcompat", version.ref = "appcompat" } material = { module = "com.google.android.material:material", version.ref = "material" } kotlinx-coroutines-android = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-android", version.ref = "coroutines" } retrofit = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" } retrofit-converter-gson = { module = "com.squareup.retrofit2:converter-gson", version.ref = "retrofit" } dagger-hilt-android = { module = "com.google.dagger:hilt-android", version.ref = "dagger" } dagger-hilt-compiler = { module = "com.google.dagger:hilt-compiler", version.ref = "dagger" } lifecycle-viewmodel-ktx = { module = "androidx.lifecycle:lifecycle-viewmodel-ktx", version.ref = "lifecycle" } lifecycle-runtime-ktx = { module = "androidx.lifecycle:lifecycle-runtime-ktx", version.ref = "lifecycle" } lifecycle-livedata-ktx = { module = "androidx.lifecycle:lifecycle-livedata-ktx", version.ref = "lifecycle" } room-runtime = { module = "androidx.room:room-runtime", version.ref = "room" } room-ktx = { module = "androidx.room:room-ktx", version.ref = "room" } [plugins] androidApplication = { id = "com.android.application", version = "8.4.0" } kotlinAndroid = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" } kotlinKapt = { id = "kotlin-kapt", version.ref = "kotlin" } daggerHiltPlugin = { id = "com.google.dagger.hilt.android", version = "2.51" } """ * Then, reference the libraries and plugins in your "build.gradle.kts" file: """kotlin plugins { alias(libs.plugins.androidApplication) alias(libs.plugins.kotlinAndroid) alias(libs.plugins.kotlinKapt) alias(libs.plugins.daggerHiltPlugin) } android { // ... } dependencies { implementation(libs.androidx.core.ktx) implementation(libs.androidx.appcompat) implementation(libs.material) implementation(libs.kotlinx.coroutines.android) implementation(libs.retrofit) implementation(libs.retrofit.converter.gson) implementation(libs.dagger.hilt.android) kapt(libs.dagger.hilt.compiler) implementation(libs.lifecycle.viewmodel.ktx) implementation(libs.lifecycle.runtime.ktx) implementation(libs.lifecycle.livedata.ktx) implementation(libs.room.runtime) kapt(libs.room.compiler) implementation(libs.room.ktx) } """ **Don't Do This:** * Ignoring the TOML file once created. Regularly update it as dependencies get updates. * Mixing versions defined in catalogs and direct dependencies defined in the build script. **Why:** * **Centralized version management:** Simplifies updating dependencies across all modules. * **Code reuse:** Avoids duplicate dependency declarations. * **Improved readability:** Makes the "build.gradle.kts" files cleaner and easier to understand. ## 2. Code Analysis and Linting ### 2.1. Standard Enable and configure static analysis tools like Android Lint, detekt, and Ktlint for automated code review. **Do This:** * Configure Android Lint in "build.gradle.kts": """kotlin android { lint { abortOnError = true // Fail build on lint errors checkAllWarnings = true // Treat all warnings as errors // Enable or disable specific lint checks disable("VectorDrawableCompat") enable("ObsoleteLayoutParam") } } """ * Integrate detekt for Kotlin code style and complexity analysis: """kotlin // Top-level build.gradle.kts plugins { id("io.gitlab.arturbosch.detekt").version("1.23.4") } // In your module's build.gradle.kts apply(plugin = "io.gitlab.arturbosch.detekt") detekt { config = files("detekt.yml") // Configuration file for detekt rules buildUponDefaultConfig = true } """ Create a "detekt.yml" file with custom rules and configurations: """yaml # detekt.yml complexity: LongParameterList: threshold: 5 ComplexMethod: threshold: 20 TooManyFunctions: threshold: 20 style: MaxLineLength: maxLineLength: 120 """ * Use Ktlint: Include Ktlint Gradle plugin. """kotlin plugins { id("org.jlleitschuh.gradle.ktlint").version("12.1.0") } """ * And then you can execute via gradle "ktlintFormat" and "ktlintCheck". And integrate this checks into your CI/CD pipeline **Don't Do This:** * Ignoring Lint warnings and errors. Treat them seriously and resolve them promptly. * Using default detekt configuration without customization. Adapt detekt rules to your project's needs. * Skipping code analysis in CI/CD pipelines. * Not using editorconfig files for consistent code style regarding indents and line endings between contributors. **Why:** * **Code Quality:** Static analysis tools identify potential bugs, code smells, and style violations early in the development process. * **Consistency:** Enforce coding standards across the entire codebase. * **Maintainability:** Reduce technical debt and simplify future code modifications. **Anti-pattern:** * Disabling useful lint checks without a valid reason. * Ignoring detekt findings and accumulating code quality issues. **Specific Notes for Kotlin Android:** Utilize Android Lint to detect Android-specific issues, such as performance problems in UI layouts or misuse of Android APIs. Customize Lint rules to match your project's requirements. Also utilize detekt rules related to Android to enforce best practices. ## 3. Asynchronous Programming and Concurrency ### 3.1. Standard Prefer Kotlin Coroutines for asynchronous programming in Android. Avoid traditional approaches like "AsyncTask" and "Thread". **Do This:** * Use "viewModelScope" or "lifecycleScope" for launching coroutines from "ViewModel" or "LifecycleOwner" components. """kotlin class MyViewModel : ViewModel() { private val _uiState = MutableLiveData<UiState>() val uiState: LiveData<UiState> = _uiState fun fetchData() { viewModelScope.launch { _uiState.value = UiState.Loading try { val data = withContext(Dispatchers.IO) { // Perform network request or other long-running operation apiService.getData() } _uiState.value = UiState.Success(data) } catch (e: Exception) { _uiState.value = UiState.Error(e) } } } } """ * Use "suspend" functions for asynchronous operations and "withContext" to switch dispatchers. """kotlin suspend fun performLongOperation(): Result<DataType> = withContext(Dispatchers.IO) { try { // Perform blocking I/O operation val result = ... Result.success(result) } catch (e: Exception) { Result.failure(e) } } """ * Handle asynchronous exceptions correctly using "try/catch" blocks within coroutines. * Use flows for handling streams of data over time. """kotlin val dataFlow: Flow<DataType> = flow { while (true) { val data = fetchDataFromSource() emit(data) delay(1000) // Emit data every 1 second } }.flowOn(Dispatchers.IO) """ **Don't Do This:** * Performing long-running operations on the main thread without using coroutines. * Ignoring cancellation signals in coroutines. * Blocking the main thread with "Thread.sleep" or similar constructs. * Using "AsyncTask" for new code. * Directly manipulating UI elements from background threads without proper context switching. **Why:** * **Simplicity:** Coroutines provide a more structured and readable way to handle asynchronous operations compared to callbacks or RxJava. * **Performance:** Coroutines are lightweight and efficient, reducing overhead compared to traditional threads. * **Structured Concurrency:** Coroutines simplify concurrent tasks through structured concurrency primitives (e.g., "async", "await"). **Anti-pattern:** * Launching coroutines without a defined scope (e.g., using "GlobalScope", which can lead to memory leaks). * Nested callbacks leading to "callback hell". **Specific Notes for Kotlin Android:** * Utilize "lifecycleScope" for Activity/Fragment specific coroutines, and "viewModelScope" for ViewModel-bound coroutines. * Wrap long-running operations in "withContext(Dispatchers.IO)" to avoid blocking the main thread ### 3.2. Executors and Thread Pools Be aware when using "Executors" and "Thread Pools". Explicitly manage lifecycles of long lived "Executors". Coroutines should be the preferred concurrency mechanism **Do This:** * Use "Executors.newFixedThreadPool(4)" for CPU-bound operations where more control than a Coroutine is desired. * Shutdown executor services when resources aren't required anymore """kotlin val executorService = Executors.newFixedThreadPool(4) fun submitTask(task: Runnable) { executorService.submit(task) } fun shutdown() { executorService.shutdown() try { if (!executorService.awaitTermination(5, TimeUnit.SECONDS)) { executorService.shutdownNow() } } catch (e: InterruptedException) { executorService.shutdownNow() } } """ **Don't Do This:** * Creating uncapped threads, as this could lead to resource exhaustion. ## 4. Testing ### 4.1. Standard Write comprehensive unit and integration tests using JUnit, Mockito/Mockk, and Espresso for UI testing. **Do This:** * Use JUnit for unit tests: """kotlin import org.junit.Assert.assertEquals import org.junit.Test class ExampleUnitTest { @Test fun addition_isCorrect() { assertEquals(4, 2 + 2) } } """ * Use Mockito or Mockk for mocking dependencies in unit tests: """kotlin import io.mockk.every import io.mockk.mockk import io.mockk.verify import org.junit.Test class MyClassTest { @Test fun testMyMethod() { val dependency = mockk<MyDependency>() every { dependency.doSomething() } returns "mocked result" val myClass = MyClass(dependency) val result = myClass.myMethod() assertEquals("mocked result", result) verify { dependency.doSomething() } } } """ * Use Espresso for UI tests: """kotlin import androidx.test.espresso.Espresso.onView import androidx.test.espresso.action.ViewActions.click import androidx.test.espresso.assertion.ViewAssertions.matches import androidx.test.espresso.matcher.ViewMatchers.withId import androidx.test.espresso.matcher.ViewMatchers.withText import androidx.test.ext.junit.rules.ActivityScenarioRule import org.junit.Rule import org.junit.Test class MainActivityTest { @get:Rule val activityRule = ActivityScenarioRule(MainActivity::class.java) @Test fun testButtonClick() { onView(withId(R.id.myButton)).perform(click()) onView(withId(R.id.myTextView)).check(matches(withText("Button Clicked!"))) } } """ * Use Turbine to test Kotlin flows. """kotlin import app.cash.turbine.test import kotlinx.coroutines.flow.flow import kotlinx.coroutines.runBlocking import org.junit.Test import kotlin.time.Duration.Companion.seconds class ExampleFlowTest { @Test fun testFlowEmissions() = runBlocking { val flow = flow { emit(1) emit(2) emit(3) } flow.test(timeout = 2.seconds) { assertEquals(1, awaitItem()) assertEquals(2, awaitItem()) assertEquals(3, awaitItem()) awaitComplete() } } } """ **Don't Do This:** * Skipping unit tests for critical logic. * Writing fragile UI tests that break easily due to minor UI changes. * Ignoring code coverage metrics. Aim for high code coverage to ensure thorough testing. * Relying solely on manual testing without automated tests. **Why:** * **Reliability:** Tests ensure that code behaves as expected and prevent regressions. * **Maintainability:** Tests make it easier to refactor and modify code without introducing bugs. * **Quality:** Tests improve the overall quality of the application. **Anti-pattern:** * Writing tests that are too complex or tightly coupled to implementation details. * Mocking everything instead of testing actual behavior. * Not using dependency injection, this leads to difficulties when mocking components. **Specific Notes for Kotlin Android:** * Use "TestCoroutineDispatcher" from "kotlinx-coroutines-test" to control the execution of coroutines in tests. * Use Hilt's testing APIs for integration testing of components that use dependency injection. ## 5. Logging and Monitoring ### 5.1. Standard Implement comprehensive logging using Timber and integrate with crash reporting tools like Firebase Crashlytics. **Do This:** * Use Timber for logging: """kotlin import timber.log.Timber class MyClass { fun myMethod(value: String) { Timber.d("myMethod called with value: %s", value) try { // Some code that may throw an exception } catch (e: Exception) { Timber.e(e, "Exception occurred in myMethod") } } init { if (BuildConfig.DEBUG) { Timber.plant(Timber.DebugTree()) } else { Timber.plant(CrashReportingTree()) } } } private class CrashReportingTree : Timber.Tree() { override fun log(priority: Int, tag: String?, message: String, t: Throwable?) { if (priority == Log.ERROR || priority == Log.WARN) { // Send error logs to crash reporting service (e.g., Firebase Crashlytics) FirebaseCrashlytics.getInstance().log(message) t?.let { FirebaseCrashlytics.getInstance().recordException(it) } } } } """ * Integrate Firebase Crashlytics for crash reporting: 1. Add Firebase Crashlytics dependency in "build.gradle.kts": """kotlin dependencies { implementation("com.google.firebase:firebase-crashlytics-ktx:18.6.3") // Also requires Google Services plugin } """ 2. Upload the mapping file during builds process, this is configured through your build tooling * Use appropriate log levels (VERBOSE, DEBUG, INFO, WARN, ERROR) based on the severity of the message. * Log meaningful contextual information to help diagnose issues. **Don't Do This:** * Using "System.out.println" for logging. * Logging sensitive information (e.g., passwords, API keys) in production builds. * Ignoring crash reports and failing to address recurring issues. **Why:** * **Debugging:** Logs provide valuable insights into the behavior of the application and help identify the root cause of issues. * **Monitoring:** Crash reports enable proactive identification and resolution of crashes in production. * **Auditing:** Logs can be used to track user activity and ensure compliance with security and privacy policies. **Anti-pattern:** * Over-logging, which can impact performance and make it difficult to find relevant information. * Logging exceptions without including the exception stack trace. **Specific Notes for Kotlin Android:** * Plant different timber trees for debug and release mode. In debug mode you can see the logs in the console. Whereas in release mode data is sent to the crash reporting tool. * Use Timber's tag functionality to add context to log messages. ## 6. Proguard/R8 ### 6.1. Standard Enable Proguard or R8 for code shrinking, obfuscation, and optimization in release builds. **Do This:** * Enable Proguard/R8 in "build.gradle.kts": """kotlin android { buildTypes { release { isMinifyEnabled = true isShrinkResources = true //Remove unused resources proguardFiles( getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro" ) } } } """ * Create a "proguard-rules.pro" file to specify custom Proguard/R8 rules. """pro # Keep class names used in reflection -keep class com.example.myapp.MyReflectedClass { <methods>; <fields>; } # Keep class names used in JSON serialization/deserialization -keep class com.example.myapp.MyDataClass { <fields>; } # Keep entry points (Activities, Services, BroadcastReceivers, ContentProviders) -keep public class *.MyActivity -keep public class *.MyService -keep public class *.MyBroadcastReceiver -keep public class *.MyContentProvider # Keep View subclasses used in XML Layouts -keep public class * extends android.view.View { <init>(android.content.Context); <init>(android.content.Context, android.util.AttributeSet); <init>(android.content.Context, android.util.AttributeSet, int); public void set*(***); public *** get*(); } """ * Test release builds thoroughly after enabling Proguard/R8 to ensure that the application functions correctly. **Don't Do This:** * Disabling Proguard/R8 in release builds. * Using default Proguard/R8 configuration without customization. * Ignoring Proguard/R8 warnings and errors. **Why:** * **Security:** Obfuscation makes it more difficult for attackers to reverse engineer the application. * **Performance:** Code shrinking and optimization reduce the size of the APK and improve runtime performance. * **APK Size:** Removes unused code and resources. **Anti-pattern:** * Over-using "-keep" rules, which can reduce the effectiveness of code shrinking and obfuscation. * Not testing release builds before publishing to the Play Store. **Specific Notes for Kotlin Android:** * Keep Kotlin reflection metadata and coroutine debug metadata if needed. * Use "-keepnames" or "-keepclassmembers" to preserve class and member names used in reflection or data binding. * Always check for exceptions and crashes related to class not found exceptions in obfuscated builds ## 7. CI/CD Integration ### 7.1. Standard Integrate with CI/CD (Continuous Integration/Continuous Deployment) pipelines using tools like Jenkins, GitLab CI, GitHub Actions, or Bitrise. **Do This:** * Automate build, test, and deployment processes. """yaml # .github/workflows/android.yml name: Android CI on: push: branches: [ "main" ] pull_request: branches: [ "main" ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up JDK 17 uses: actions/setup-java@v4 with: java-version: '17' distribution: 'temurin' - name: Grant execute permission for gradlew run: chmod +x gradlew - name: Build with Gradle run: ./gradlew assembleRelease - name: Upload APK uses: actions/upload-artifact@v3 with: name: app-release.apk path: app/build/outputs/apk/release/app-release.apk """ * Configure CI/CD to run static analysis tools, unit tests, and UI tests. * Automate code signing and APK publishing to the Play Store. * Use environment variables for sensitive information (e.g., API keys, signing passwords). **Don't Do This:** * Manually building and deploying the application. * Skipping automated tests in CI/CD pipelines. * Committing sensitive information to the repository. **Why:** * **Automation:** CI/CD automates repetitive tasks, reducing manual effort and errors. * **Faster Feedback:** CI/CD provides rapid feedback on code changes, allowing developers to identify and fix issues quickly. * **Continuous Deployment:** CI/CD enables continuous deployment of new features and bug fixes to users. **Anti-pattern:** * Creating CI/CD pipelines that are too complex or difficult to maintain. * Not monitoring CI/CD pipeline performance and addressing bottlenecks. **Specific Notes for Kotlin Android:** * Use Gradle plugins for configuring CI/CD tasks. * Integrate with Firebase App Distribution for distributing beta builds to testers. * Use emulator snapshots in CI environment to save time for configuring emulator in each build step
# State Management Standards for Kotlin Android This document outlines the coding standards and best practices for managing application state in Kotlin Android projects. Proper state management is crucial for maintainability, testability, performance, and overall application architecture. It emphasizes modern approaches using Kotlin's features and the Android Jetpack libraries. This guide is designed for Kotlin Android developers and serves as a reference for AI coding assistants. ## 1. Guiding Principles * **Single Source of Truth:** Every piece of state should exist in only one place in the application. This prevents inconsistencies and simplifies debugging. * **Unidirectional Data Flow:** Data should flow in a single direction through the application. This makes the flow predictable and easier to reason about. * **Immutability:** Prefer immutable data structures. This reduces the risk of accidental state changes and facilitates concurrent access. * **Explicit State:** UI components should declare their state explicitly rather than relying on implicit or hidden state. * **Separation of Concerns:** Decouple UI code from business logic and state management. This improves testability and maintainability. ## 2. Architectural Patterns for State Management ### 2.1. Model-View-Intent (MVI) MVI is a reactive architectural pattern that enforces a unidirectional data flow. * **Model:** Represents the immutable state of the UI. * **View:** Renders the UI based on the current state. Observes state, and emits intents. * **Intent:** Represents the user's intention to perform an action. * **Reducer:** Pure function which modifies the state based on intent and previous state. * **Effect:** Side Effect which reacts to reducer changes. **Do This:** * Use MVI when building complex UIs with a lot of dynamic state. * Employ libraries like Turbine for testing. * Consider Coroutines Flow for efficient state updates. **Don't Do This:** * Don't mutate the state directly inside the View. * Don't perform side effects within the reducer. **Code Example:** """kotlin import kotlinx.coroutines.flow.* // 1. Define the state data class MainState( val isLoading: Boolean = false, val data: String? = null, val error: String? = null ) // 2. Define the intent sealed class MainIntent { object LoadData : MainIntent() data class UpdateData(val newData: String) : MainIntent() } // 3. Define the effect sealed class MainEffect { data class ShowError(val message: String) : MainEffect() } // 4. The ViewModel holding the state and handling intents class MainViewModel { private val _state = MutableStateFlow(MainState()) val state: StateFlow<MainState> = _state.asStateFlow() //Expose for the view to render private val _effect: MutableSharedFlow<MainEffect> = MutableSharedFlow() val effect = _effect.asSharedFlow() //Expose for the view to react fun processIntent(intent: MainIntent) { when (intent) { MainIntent.LoadData -> loadData() is MainIntent.UpdateData -> updateData(intent.newData) } } private fun loadData() { _state.update { it.copy(isLoading = true, error = null) } // Simulate loading data from a repository viewModelScope.launch { try { //Simulate IO. delay(1000) _state.update { it.copy(isLoading = false, data = "Loaded data") } } catch (e: Exception) { _state.update { it.copy(isLoading = false, error = e.message) } _effect.emit(MainEffect.ShowError("Failed to load data")) } } } private fun updateData(newData: String) { _state.update { it.copy(data = newData) } } } // 5. The View (Activity/Fragment) class MainActivity : ComponentActivity() { private val viewModel: MainViewModel by viewModels() override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContent { val state by viewModel.state.collectAsState() LaunchedEffect(Unit) { //Collect the ViewEffect viewModel.effect.collect{ effect -> when(effect) { is MainEffect.ShowError -> { //Show error message via Toast or Compose Snackbar Toast.makeText(this@MainActivity, effect.message, Toast.LENGTH_SHORT).show() } } } } Column { if (state.isLoading) { Text("Loading...") } else if (state.error != null) { Text("Error: ${state.error}") } else { Text("Data: ${state.data ?: "No data"}") Button(onClick = { viewModel.processIntent(MainIntent.LoadData) }) { Text("Load Data") } Button(onClick = { viewModel.processIntent(MainIntent.UpdateData("New Data")) }) { Text("Update Data") } } } } } } """ **Why:** * MVI promotes a clear separation of concerns and predictable state management, making the app more maintainable and testable. The explicit "Effect" makes side effects predictable. **Anti-Pattern:** * Integrating side effects (e.g., network calls, database updates) directly into the View or Model makes the app harder to test and maintain. Instead, side effects should be routed and captured within the Effect. ### 2.2. Model-View-ViewModel (MVVM) with StateFlow/LiveData MVVM is an architectural pattern that separates the UI (View) from the data and logic (ViewModel). * **Model:** Represents the data layer and business logic. * **View:** Displays the data and forwards user actions to the ViewModel. * **ViewModel:** Exposes data streams for the View to observe and handles user actions by interacting with the Model. It holds the *state*. **Do This:** * Use MVVM as the standard architecture for building most UIs. * Use "StateFlow" for complex state that benefits from reactive updates and "LiveData" for simpler scenarios or when interoperability with older code is necessary. Use "SharedFlow" for passing one-off events. * Use Coroutines to perform asynchronous operations in the ViewModel. **Don't Do This:** * Don't put UI logic in the ViewModel. * Don't reference "Context" or "View" instances in the ViewModel. **Code Example:** """kotlin import androidx.lifecycle.* import kotlinx.coroutines.flow.* import kotlinx.coroutines.launch // 1. Define the state data class UserState( val isLoading: Boolean = false, val userName: String? = null, val errorMessage: String? = null ) // 2. The ViewModel holding the state class UserViewModel(private val userRepository: UserRepository) : ViewModel() { private val _userState = MutableStateFlow(UserState()) val userState: StateFlow<UserState> = _userState.asStateFlow() init { loadUser() } fun loadUser() { viewModelScope.launch { _userState.update { it.copy(isLoading = true, errorMessage = null) } try { val user = userRepository.getUser() _userState.update { it.copy(isLoading = false, userName = user.name) } } catch (e: Exception) { _userState.update { it.copy(isLoading = false, errorMessage = e.message) } } } } } // 3. The Repository (Model) class UserRepository { // Simulate network call suspend fun getUser(): User { delay(1000) // Simulate network delay return User("John Doe") } } data class User(val name: String) // 4. The View (Activity/Fragment) class UserActivity : ComponentActivity() { private val userViewModel: UserViewModel by viewModels { UserViewModelFactory((application as YourApplication).userRepository) } override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContent { val state by userViewModel.userState.collectAsState() Column { if (state.isLoading) { Text("Loading...") } else if (state.errorMessage != null) { Text("Error: ${state.errorMessage}") } else { Text("User: ${state.userName ?: "No user"}") } } } } } class UserViewModelFactory(private val userRepository: UserRepository) : ViewModelProvider.Factory { override fun <T : ViewModel> create(modelClass: Class<T>): T { if (modelClass.isAssignableFrom(UserViewModel::class.java)) { @Suppress("UNCHECKED_CAST") return UserViewModel(userRepository) as T } throw IllegalArgumentException("Unknown ViewModel class") } } """ **Why:** * MVVM separates UI logic from business logic, making the app more testable and maintainable. StateFlow/LiveData provide a reactive way to update the UI when the state changes. * ViewModel survives configuration changes, preventing data loss. **Anti-Pattern:** * Putting business logic in the Activity/Fragment makes the app harder to test and maintain. ### 2.3. Unidirectional Data Flow with Jetpack Compose Jetpack Compose encourages a unidirectional data flow where UI components are functions of state. **Do This:** * Use "remember" to hold state within composables. * Use "MutableState" or "mutableStateOf" to create observable state. * Use "LaunchedEffect" or "rememberCoroutineScope" to perform side effects. Handle UI events with simple callbacks. **Don't Do This:** * Don't modify state directly within the composable without using "remember" and "mutableStateOf". * Don't perform complex business logic inside composables. **Code Example:** """kotlin import androidx.compose.runtime.* import androidx.compose.ui.tooling.preview.Preview import androidx.compose.material.* import androidx.compose.foundation.layout.* @Composable fun CounterApp() { Column { // 1. Define and hold the state var count by remember { mutableStateOf(0) } // 2. Display the state Text(text = "Count: $count") // 3. Allow users to modify the state via UI events Row { Button(onClick = { count++ }) { Text("Increment") } Button(onClick = { count-- }) { Text("Decrement") } } } } @Preview @Composable fun PreviewCounterApp() { CounterApp() } """ **Why:** * Compose promotes a declarative UI paradigm, making it easier to reason about and maintain the UI. Immutable data structures greatly improve testability within Composables. * Unidirectional data flow simplifies state management and reduces the risk of unexpected side effects. **Anti-Pattern:** * Modifying external state directly within a composable makes the UI harder to reason about and test. ### 2.4. Using Redux with Kotlin Redux is a state management pattern often used in complex applications. It is inspired by the Elm Architecture. It features a single store and pure reducers for processing state. **Do This:** * Consider Redux for apps requiring complex state management and time-travel debugging or state persistence. **Don't Do This:** * Avoid overusing Redux for simple apps, as it can add unnecessary complexity. **Code Example:** """kotlin import kotlinx.coroutines.flow.* import kotlinx.coroutines.launch import androidx.lifecycle.* // 1. Define the state data class AppState(val count: Int = 0) // 2. Define the actions sealed class AppAction { object Increment : AppAction() object Decrement : AppAction() } // 3. Define the reducer fun reducer(state: AppState, action: AppAction): AppState { return when (action) { AppAction.Increment -> state.copy(count = state.count + 1) AppAction.Decrement -> state.copy(count = state.count - 1) } } // 4. Define the store class Store(initialState: AppState) { private val _state = MutableStateFlow(initialState) val state: StateFlow<AppState> = _state.asStateFlow() fun dispatch(action: AppAction) { _state.value = reducer(_state.value, action) } } // 5. ViewModel usage: class MyViewModel : ViewModel() { private val store = Store(AppState()) val state: StateFlow<AppState> = store.state fun increment() { store.dispatch(AppAction.Increment) } fun decrement() { store.dispatch(AppAction.Decrement) } } // 6. Activity/Fragment Usage class ReduxActivity : ComponentActivity() { private val viewModel: MyViewModel by viewModels() override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContent { val state by viewModel.state.collectAsState() Column { Text("Count: ${state.count}") Button(onClick = { viewModel.increment() }) { Text("Increment") } Button(onClick = { viewModel.decrement() }) { Text("Decrement") } } } } } """ **Why:** * Redux enforces a strict unidirectional data flow and makes state management predictable * Redux simplifies debugging by providing a single source of truth. **Anti-Pattern:** * Using Redux for simple state makes the application overly complex. * Mutating state directly in the reducer breaks the immutability principle. ## 3. Technology-Specific Details ### 3.1. Handling Configuration Changes * **ViewModel:** Use "ViewModel" to retain data across configuration changes. * **"rememberSaveable" in Compose:** Use "rememberSaveable" in Compose to save and restore state across configuration changes. **Code Example:** """kotlin import androidx.compose.runtime.* import androidx.compose.runtime.saveable.rememberSaveable import androidx.compose.material.Text @Composable fun MyComposable() { var myValue by rememberSaveable { mutableStateOf("Initial Value") } Text(text = "My Value: $myValue") // ... } """ ### 3.2. Saving UI State * **"onSaveInstanceState()":** Use "onSaveInstanceState()" in Activities/Fragments to save UI state when the app is backgrounded. * **"rememberSavable()":** Utilize "rememberSavable" to automatically save state across activity recreation. **Code Example:** """kotlin import android.os.Bundle import androidx.activity.ComponentActivity import androidx.activity.compose.setContent import androidx.compose.foundation.layout.Column class SavingActivity : ComponentActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContent { Column { MyComposable() } } } } """ ### 3.3. Use of "SavedStateHandle" * Instantiate your "ViewModel" with the "SavedStateHandle" for state persistence across process death scenarios: """kotlin import androidx.lifecycle.* class MyViewModel(private val savedStateHandle: SavedStateHandle) : ViewModel() { private val _myState = MutableLiveData<String>() val myState: LiveData<String> = _myState init { // Retrieve the saved state, or use a default value _myState.value = savedStateHandle.get<String>("my_state_key") ?: "Default Value" } fun updateState(newValue: String) { _myState.value = newValue // Save the state savedStateHandle.set("my_state_key", newValue) } } """ **Why:** * "SavedStateHandle" offers a robust solution to manage state restoration during process death, providing data that survives beyond configuration changes, ensuring a reliable user experience. ### 3.4 Jetpack DataStore Use Jetpack DataStore instead of shared preferences for storing key-value pairs or typed objects. DataStore offers coroutines and Flow support, transactional APIs, and strong consistency. """kotlin import android.content.Context import androidx.datastore.core.DataStore import androidx.datastore.preferences.core.Preferences import androidx.datastore.preferences.core.edit import androidx.datastore.preferences.core.intPreferencesKey import androidx.datastore.preferences.preferencesDataStore import kotlinx.coroutines.flow.Flow import kotlinx.coroutines.flow.map // Create DataStore val Context.dataStore: DataStore<Preferences> by preferencesDataStore(name = "settings") // Example preferences keys object StoreKeys { val exampleCounter = intPreferencesKey("example_counter") } // Read the value val exampleCounterFlow: Flow<Int> = context.dataStore.data .map { preferences -> preferences[StoreKeys.exampleCounter] ?: 0 } // Update the value suspend fun incrementCounter(context: Context) { context.dataStore.edit { preferences -> val currentCounterValue = preferences[StoreKeys.exampleCounter] ?: 0 preferences[StoreKeys.exampleCounter] = currentCounterValue + 1 } } """ **Why:** * DataStore provides a modern and type-safe way to persist data, offering improved performance and consistency compared to SharedPreferences. It also works seamlessly with Kotlin Coroutines and Flow. ## 4. Core Kotlin Features ### 4.1. Immutability * Use "val" for immutable variables. * Use data classes for immutable data structures. * Use "copy()" method to create modified copies of data classes. **Code Example:** """kotlin data class Person(val name: String, val age: Int) fun main() { val person1 = Person("Alice", 30) val person2 = person1.copy(age = 31) // Create a new instance with a modified property println(person1) println(person2) } """ ### 4.2. Coroutines * Use Coroutines for asynchronous operations. * Use "viewModelScope" for launching Coroutines in ViewModels. * Use "lifecycleScope" for launching Coroutines in Activities/Fragments. **Code Example:** """kotlin import androidx.lifecycle.* import kotlinx.coroutines.launch class MyViewModel : ViewModel() { fun fetchData() { viewModelScope.launch { // Perform asynchronous operation val result = performNetworkRequest() // Update UI } } suspend fun performNetworkRequest(): String { delay(1000) // Simulate network delay return "Data from network" } } """ ### 4.3. Kotlin Flow * Use "StateFlow" for observable state holders that emit current state and updates. * Use "SharedFlow" for emitting events or one-off updates. * Use "collectAsState()" in Compose to collect Flow values. **Code Example:** """kotlin import androidx.compose.runtime.* import kotlinx.coroutines.flow.* class MyViewModel : ViewModel() { private val _myState = MutableStateFlow("Initial Value") val myState: StateFlow<String> = _myState.asStateFlow() fun updateState(newValue: String) { _myState.value = newValue } } @Composable fun MyComposable(viewModel: MyViewModel) { val stateValue by viewModel.myState.collectAsState() Text(text = "State Value: $stateValue") } """ ## 5. Testing State Management ### 5.1. Unit Tests * Write unit tests for ViewModels, reducers, and other state management components. * Mock dependencies to isolate units of code. * Use "Turbine" library with Flow to collect and verify values: """kotlin import kotlinx.coroutines.test.runTest import app.cash.turbine.test import kotlinx.coroutines.flow.MutableStateFlow import kotlin.test.Test import kotlin.test.assertEquals class ViewModelTest { @Test fun "test state updates"() = runTest { val viewModel = MyViewModel() val stateFlow = MutableStateFlow<String>("initial") stateFlow.test { assertEquals("initial", awaitItem()) stateFlow.emit("new") assertEquals("new", awaitItem()) cancelAndConsumeRemainingEvents() } } } """ ### 5.2. UI Tests * Write UI tests to verify the behavior of the UI when state changes. * Use "ComposeTestRule" in Compose to interact with UI elements. """kotlin import androidx.compose.ui.test.junit4.createComposeRule import androidx.compose.ui.test.onNodeWithText import androidx.compose.ui.test.performClick import org.junit.Rule import org.junit.Test class ComposeUITest { @get:Rule val composeTestRule = createComposeRule() @Test fun testIncrementButton() { composeTestRule.setContent { CounterApp() } composeTestRule.onNodeWithText("Increment").performClick() composeTestRule.onNodeWithText("Count: 1").assertExists() } } """ ## 6. Performance Considerations * Avoid unnecessary state updates. Only update the state when it actually changes. * Use immutable data structures to prevent accidental state changes. * Use "collectAsStateWithLifecycle()" for collecting "StateFlow" in compose when running in the ui layer. This prevents the state from being collected when the UI is not visible. * Use appropriate data structures for storing state (e.g., "ImmutableList", "ImmutableMap"). ## 7. Security Considerations * Protect sensitive data by encrypting it before storing it. * Avoid storing sensitive data in UI state. ## 8. Deprecated Features / Known Issues * Be aware that "LiveData" lacks some of the advanced features offered by Kotlin Flows (e.g., complex transformations, backpressure handling). Consider migrating "LiveData" to "StateFlow". * Be mindful of potential memory leaks when using "rememberCoroutineScope" within a Composable. Ensure that the scope is properly tied to the lifecycle of the Composable. Ensure that LaunchedEffect keys are only triggered when changes are truly needed. This comprehensive guide provides a strong foundation for managing state in Kotlin Android applications and aims to assist developers in creating robust, maintainable, and performant applications. Keeping abreast of the latest advancements and best practices will be critical in the evolution of Kotlin Android development.
# Security Best Practices Standards for Kotlin Android This document outlines the security best practices for Kotlin Android development, providing guidelines for developers, informing architecture decisions, and serving as a reference for AI coding assistants. Adhering to these standards will minimize vulnerabilities, enhance application security, and ensure compliance with industry best practices. ## 1. Secure Data Storage ### 1.1 Encryption of Sensitive Data **Standard:** All sensitive data must be encrypted at rest and in transit. **Why:** Protecting data against unauthorized access in case of device compromise or data interception. **Do This:** * Utilize Android's "EncryptedSharedPreferences" or Jetpack Security library for encrypting data stored in shared preferences and files. * Employ SQLCipher for encrypting SQLite databases. * Use TLS/SSL for all network communications. **Don't Do This:** * Store sensitive data in plain text. * Use hardcoded encryption keys. * Rely on obfuscation as a primary security measure. **Code Example: EncryptedSharedPreferences** """kotlin import androidx.security.crypto.EncryptedSharedPreferences import androidx.security.crypto.MasterKeys import android.content.Context class SecureStorageManager(private val context: Context) { private val masterKeyAlias = MasterKeys.getOrCreate(MasterKeys.AES256_GCM_SPEC) private val sharedPreferences = EncryptedSharedPreferences.create( "secret_shared_prefs", masterKeyAlias, context, EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV, EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM ) fun saveSecret(secret: String) { sharedPreferences.edit().putString("my_secret", secret).apply() } fun getSecret(): String? { return sharedPreferences.getString("my_secret", null) } fun deleteSecret() { sharedPreferences.edit().remove("my_secret").apply() } } // Usage val secureStorage = SecureStorageManager(context) secureStorage.saveSecret("My Super Secret Value") val retrievedSecret = secureStorage.getSecret() println("Retrieved secret: $retrievedSecret") secureStorage.deleteSecret() """ **Code Example: SQLCipher** """kotlin import net.sqlcipher.database.SQLiteDatabase import net.sqlcipher.database.SQLiteOpenHelper import android.content.Context import android.content.ContentValues class DatabaseHelper(context: Context) : SQLiteOpenHelper(context, DATABASE_NAME, null, DATABASE_VERSION) { companion object { private const val DATABASE_NAME = "my_secure_database.db" private const val DATABASE_VERSION = 1 private const val PASSWORD = "my_secret_password" //Important: Manage password securely and NEVER hardcode it!!! const val TABLE_NAME = "users" const val COLUMN_ID = "_id" const val COLUMN_USERNAME = "username" const val COLUMN_PASSWORD = "password" } override fun onCreate(db: SQLiteDatabase) { db.execSQL("CREATE TABLE $TABLE_NAME ($COLUMN_ID INTEGER PRIMARY KEY, $COLUMN_USERNAME TEXT, $COLUMN_PASSWORD TEXT)") } override fun onUpgrade(db: SQLiteDatabase, oldVersion: Int, newVersion: Int) { db.execSQL("DROP TABLE IF EXISTS $TABLE_NAME") onCreate(db) } fun insertUser(username: String, password: String) { writableDatabase.use { db -> val values = ContentValues().apply { put(COLUMN_USERNAME, username) put(COLUMN_PASSWORD, password) } db.insert(TABLE_NAME, null, values) } } fun readUsers():Unit { readableDatabase.use {db -> val cursor = db.query(TABLE_NAME, null, null, null, null, null, null) with(cursor) { while (moveToNext()) { val userId = getInt(getColumnIndexOrThrow(COLUMN_ID)) val userName = getString(getColumnIndexOrThrow(COLUMN_USERNAME)) val password = getString(getColumnIndexOrThrow(COLUMN_PASSWORD)) println("User ID: $userId, User Name: $userName, Password: $password") } } } } override fun getWritableDatabase(password: String?): SQLiteDatabase { val db = super.getWritableDatabase(password) return db } override fun getReadableDatabase(password: String?): SQLiteDatabase { val db = super.getReadableDatabase(password) return db } fun openDatabase() : SQLiteDatabase { val database = this.writableDatabase return database } fun closeDatabase(){ this.close() } } //Initialize SQLCipher fun initializeSQLCipher(context: Context){ SQLiteDatabase.loadLibs(context) } // Example usage val helper = DatabaseHelper(context) //Get context correctly. //Initialize SQLCipher libraries initializeSQLCipher(context) //Open the database val db = helper.openDatabase() //Insert User data helper.insertUser("testUser", "password123") //Read users helper.readUsers() //Close database helper.closeDatabase() """ **Anti-Pattern:** Writing keys or passwords directly in the Kotlin/Java code or XML resource files. Keys, salts, and passwords should be managed safely outside of the app package (e.g., using the Android Keystore or a dedicated secrets management system). ### 1.2 Secure Key Management **Standard:** Protect cryptographic keys using hardware-backed Keystore systems. **Why:** Software-based key storage is vulnerable to attacks. The Keystore provides hardware-backed security that is resistant to key extraction. **Do This:** * Use the Android Keystore system to store cryptographic keys securely. * Generate keys with strong entropy. * Set appropriate key usage flags (e.g., encryption only, signing only). **Don't Do This:** * Hardcode keys in the application. * Store keys in plain text files. * Use weak or predictable key generation methods. **Code Example: Android Keystore** """kotlin import android.security.keystore.KeyGenParameterSpec import android.security.keystore.KeyProperties import java.security.KeyStore import javax.crypto.KeyGenerator class KeyStoreManager { private val keyStore: KeyStore = KeyStore.getInstance("AndroidKeyStore").apply { load(null) } fun generateKey(keyAlias: String) { if (!keyStore.containsAlias(keyAlias)) { val keyGenerator = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, "AndroidKeyStore") val keyGenParameterSpec = KeyGenParameterSpec.Builder( keyAlias, KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT ) .setBlockModes(KeyProperties.BLOCK_MODE_GCM) .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE) .setKeySize(256) .setUserAuthenticationRequired(false) // Consider user authentication .build() keyGenerator.init(keyGenParameterSpec) keyGenerator.generateKey() } } fun getKey(keyAlias: String): SecretKey? { return keyStore.getKey(keyAlias, null) as? SecretKey } fun encryptionExample(plainText: String, keyAlias: String): ByteArray { val key = getKey(keyAlias) if(key == null){ throw Exception("Key not found") } val cipher = Cipher.getInstance("AES/GCM/NoPadding") cipher.init(Cipher.ENCRYPT_MODE, key) val cipherText = cipher.doFinal(plainText.toByteArray(Charsets.UTF_8)) return cipherText } fun decryptionExample(cipherText: ByteArray, keyAlias: String):String{ val key = getKey(keyAlias) if(key == null){ throw Exception("Key not found") } val cipher = Cipher.getInstance("AES/GCM/NoPadding") cipher.init(Cipher.DECRYPT_MODE, key) val plainText = cipher.doFinal(cipherText) return String(plainText, Charsets.UTF_8) } } // Usage example val keyStoreManager = KeyStoreManager() val keyAlias = "my_secret_key" keyStoreManager.generateKey(keyAlias) val plainText = "Sensitive data to encrypt" var cipherText = keyStoreManager.encryptionExample(plainText, keyAlias) println("Encrypted data: ${cipherText.contentToString()}") val decryptedText = keyStoreManager.decryptionExample(cipherText, keyAlias) println("Decrypted data: $decryptedText") """ **Anti-Pattern:** Using shared preferences as a substitute for the Android Keystore. This is insecure and should be avoided. ### 1.3 Removal of Sensitive Data **Standard:** Ensure sensitive data is removed securely when no longer needed. **Why:** Prevents data leakage if the device is compromised or when the application is uninstalled. **Do This:** * Overwrite memory with garbage data after use. * Delete encrypted files securely. Implement standard secure deletion techniques when deleting files (e.g. overwriting). * Clear shared preferences or database entries. **Don't Do This:** * Rely on standard file deletion methods alone. * Assume data is automatically erased from memory. * Leave temporary files containing sensitive information. **Code Example: Secure File Deletion** """kotlin import java.io.File import java.io.FileOutputStream fun secureDelete(file: File) { if (file.exists()) { val fileLength = file.length() val random = java.security.SecureRandom() FileOutputStream(file).use { fos -> random.nextBytes(ByteArray(fileLength.toInt())) fos.write(ByteArray(fileLength.toInt())) } if (!file.delete()) { println("Failed to delete file") //Handle deletion errors gracefully. Potentially attempt re-deletion or flag for manual removal. } } } //Usage val myFile = File(context.filesDir, "sensitive_data.txt") myFile.writeText("This is sensitive.") secureDelete(myFile) """ **Anti-Pattern:** Leaving sensitive data in logs, even if temporarily. Logging should be carefully reviewed for sensitive data and addressed proactively. ## 2. Secure Network Communication ### 2.1 HTTPS for All Network Requests **Standard:** Use HTTPS for all network communication to protect data in transit using TLS/SSL. **Why:** Prevents eavesdropping and man-in-the-middle attacks by encrypting data transmitted over the network. **Do This:** * Use "https://" URLs for all API endpoints. * Validate SSL certificates to ensure the server is trusted. * Configure network security policies to enforce HTTPS. **Don't Do This:** * Use HTTP ("http://") for sensitive data transmissions. * Disable SSL certificate validation or ignore certificate errors. * Allow insecure connections in production. **Code Example: Enforcing HTTPS with Network Security Configuration** Create "network_security_config.xml" in "res/xml": """xml <?xml version="1.0" encoding="utf-8"?> <network-security-config> <domain-config cleartextTrafficPermitted="false"> <domain includeSubdomains="true">yourdomain.com</domain> <!-- Replace with your domain --> </domain-config> </network-security-config> """ Associate the config with your application in "AndroidManifest.xml": """xml <application android:networkSecurityConfig="@xml/network_security_config" ...> </application> """ **Code Example: Retrofit with HTTPS** """kotlin import retrofit2.Retrofit import retrofit2.converter.gson.GsonConverterFactory object ApiClient { private const val BASE_URL = "https://yourdomain.com/" // Ensure it's HTTPS val instance: ApiInterface by lazy { val retrofit = Retrofit.Builder() .baseUrl(BASE_URL) .addConverterFactory(GsonConverterFactory.create()) .build() retrofit.create(ApiInterface::class.java) } } """ **Anti-Pattern:** Hardcoding network endpoints within the app for easy modification risks releasing an app pointing to a development or debugging endpoint in production. ### 2.2 Certificate Pinning **Standard:** Implement certificate pinning to trust only specific certificates, mitigating man-in-the-middle attacks. **Why:** Protects against compromised or fraudulent certificates used in MITM attacks. **Do This:** * Pin the server's certificate or public key in the app code. * Update the pinned certificate regularly. * Provide a backup pinning configuration in case of certificate rotation. **Don't Do This:** * Rely solely on the system's trusted certificate authorities. * Hardcode certificates directly in the code without proper management. * Skip certificate validation during pinning. **Code Example: Certificate Pinning with OkHttp** """kotlin import okhttp3.CertificatePinner import okhttp3.OkHttpClient object SecureOkHttpClient { fun getUnsafeOkHttpClient(): OkHttpClient { val certificatePinner = CertificatePinner.Builder() .add("yourdomain.com", "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=") // Replace with your domain and SHA256 pin .build() return OkHttpClient.Builder() .certificatePinner(certificatePinner) .build() } } """ **Anti-Pattern:** Ignoring updates to expiration dates of Certificates. Update mechanism should be robust to avoid hardcoded pins. ### 2.3 Input Validation **Standard:** Validate all input received from external sources (network, intents, user input) to prevent injection attacks. **Why:** Prevents malicious code from being injected into the application. **Do This:** * Use parameterized queries for database access to prevent SQL injection. * Encode data appropriately before displaying it in web views. * Sanitize user input before using it in external commands. * Use Android's built-in input filters and regular expressions for validation. **Don't Do This:** * Trust user input without validation. * Construct SQL queries by concatenating strings directly. * Execute shell commands with user-provided input. **Code Example: Input Validation using Regular Expressions** """kotlin fun isValidEmail(email: String): Boolean { val emailRegex = "^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,6}$".toRegex() return emailRegex.matches(email) } // Usage val email = "test@example.com" if (isValidEmail(email)) { println("Valid email") } else { println("Invalid email") } """ **Anti-Pattern:** Neglecting to regularly update dependencies, because libraries with outdated versions sometimes contain security vulnerabilities. ## 3. Securing Application Components ### 3.1 Intent Handling **Standard:** Use explicit intents for internal communication within the application and carefully validate data received from external intents. **Why:** Prevents intent spoofing and data leakage by ensuring that only authorized components receive intents. **Do This:** * Use explicit intents when starting activities, services, and broadcast receivers within your app. * Specify the target component by its fully qualified name. * Apply permissions to restrict access to sensitive components. * Validate and sanitize any data received from implicit intents. **Don't Do This:** * Use implicit intents for sensitive operations. * Trust the source of incoming intents without validation. * Expose sensitive data through exported components. * Skip permissions for sensitive operations. **Code Example: Explicit Intent** """kotlin import android.content.Intent import android.content.Context fun startMyActivity(context: Context) { val intent = Intent(context, MyActivity::class.java) context.startActivity(intent) } """ **Anti-Pattern:** Improper Use of Implicit Intents. Only use implicit intents when absolutely necessary (e.g., opening URL, sharing content) and always validate the receiving application. ### 3.2 Permissions Management **Standard:** Request only the necessary permissions and protect sensitive operations with appropriate permissions. **Why:** Minimizes the attack surface and reduces the risk of unauthorized access to sensitive data and functionality. **Do This:** * Request permissions at runtime when needed, using the Jetpack Compose Permissions library or Activity Result APIs. * Use the principle of least privilege: only request the minimum permissions required. * Protect sensitive application components with custom permissions. **Don't Do This:** * Request all permissions at install time. * Grant unnecessary permissions to third-party libraries. * Ignore permission checks before performing sensitive operations. **Code Example: Runtime Permissions Request using Activity Result APIs** """kotlin import android.Manifest import android.content.pm.PackageManager import androidx.activity.result.contract.ActivityResultContracts import androidx.core.content.ContextCompat import androidx.fragment.app.Fragment import androidx.activity.result.ActivityResultLauncher class MyFragment : Fragment() { private lateinit var requestPermissionLauncher: ActivityResultLauncher<String> override fun onCreate() { super.onCreate() requestPermissionLauncher = registerForActivityResult( ActivityResultContracts.RequestPermission() ) { isGranted: Boolean -> if (isGranted) { // Permission is granted. Continue the action or workflow // in your app. } else { // Explain to the user that the feature is unavailable because the // features requires a permission that the user has denied. At the // same time, respect the user's decision. Don't link to system // settings in an effort to convince the user to change their // decision. } } } fun requestCameraPermission() { when { ContextCompat.checkSelfPermission( requireContext(), Manifest.permission.CAMERA ) == PackageManager.PERMISSION_GRANTED -> { // You can use the API that requires the permission. } shouldShowRequestPermissionRationale(Manifest.permission.CAMERA) -> { // Provide an additional rationale to the user. This would happen // if the user denied the request previously, but didn't check // the "Don't ask again" check box. // Show rationale UI to explain why permission is needed, then // request the permission. requestPermissionLauncher.launch(Manifest.permission.CAMERA) } else -> { // You can directly ask for the permission. requestPermissionLauncher.launch(Manifest.permission.CAMERA) } } } } """ **Anti-Pattern:** Over-permission, or requesting unnecessary permissions, erodes user trust and increases the attack surface potentially leading to permission abuse. ### 3.3 WebView Security **Standard:** Properly configure WebView instances to prevent cross-site scripting (XSS) and other vulnerabilities. **Why:** WebViews can be exploited to execute malicious JavaScript code, steal cookies, or access local resources if not configured correctly. **Do This:** * Disable JavaScript execution unless strictly necessary. * Validate and sanitize any URLs loaded in the WebView. * Use "setWebChromeClient" and "setWebViewClient" to handle JavaScript alerts and page navigation securely. * Enable Safe Browsing to protect users from malicious websites. **Don't Do This:** * Enable JavaScript execution without proper input validation. * Load untrusted or user-controlled URLs in the WebView. * Expose sensitive data to JavaScript code running in the WebView. * Ignore SSL certificate errors. **Code Example: WebView Configuration** """kotlin import android.webkit.WebView import android.webkit.WebViewClient fun configureWebView(webView: WebView) { webView.settings.javaScriptEnabled = false // Disable JavaScript if not needed webView.webViewClient = WebViewClient() // Handle page navigation // Enable Safe Browsing webView.settings.safeBrowsingEnabled = true } // Usage val myWebView = WebView(context) configureWebView(myWebView) myWebView.loadUrl("https://www.example.com") """ **Anti-Pattern:** Enabling JavaScript in WebViews without thoroughly validating and sanitizing inputs can lead to severe XSS vulnerabilities and potential data breaches. ## 4. Code Security ### 4.1 Dependency Management **Standard:** Update dependencies regularly and be aware of vulnerabilities in third-party libraries. **Why:** Outdated and vulnerable third-party libraries are a common source of security vulnerabilities. **Do This:** * Use dependency management tools like Gradle with version catalogs to manage dependencies. * Monitor dependencies for known vulnerabilities. Tools like Dependency-Check or Snyk integrate into CI/CD pipelines. * Keep dependencies updated to the latest stable versions. * Evaluate the security of third-party libraries before including them in the project. **Don't Do This:** * Use outdated or unsupported libraries. * Ignore security warnings from dependency management tools. * Blindly trust third-party code. **Code Example: Gradle Dependency Management** """gradle // build.gradle.kts (Module: app) dependencies { implementation("androidx.core:core-ktx:1.12.0") //Example implementation("androidx.appcompat:appcompat:1.6.1") implementation("com.google.android.material:material:1.12.0") //Example //Other dependencies... } """ **Anti-Pattern:** Disregarding deprecation warnings can lead to unforeseen security issues as deprecated APIs are likely to have known vulnerabilities that may not be patched in older releases. ### 4.2 Secure Coding Practices **Standard:** Follow secure coding practices to minimize vulnerabilities. **Why:** Secure coding practices reduce the likelihood of introducing vulnerabilities such as buffer overflows, format string bugs, and race conditions. **Do This:** * Perform regular security code reviews. * Use static analysis tools to identify potential vulnerabilities. * Follow secure coding guidelines for Kotlin and Android. * Implement proper error handling and logging. **Don't Do This:** * Ignore compiler warnings or static analysis results. * Write complex or convoluted code that is difficult to understand and review. * Expose sensitive data in error messages. **Code Example: Safe Integer Handling** """kotlin fun addSafely(a: Int, b: Int): Int? { return try { Math.addExact(a, b) //Throws ArithmeticException on overflow } catch (e: ArithmeticException) { null // or handle overflow appropriately } } // Usage val x = Int.MAX_VALUE val y = 1 val sum = addSafely(x, y) if (sum == null){ println("Integer overflow occurred!") } else { println("Sum: $sum") } """ **Anti-Pattern:** Neglecting to handle exceptional cases gracefully can lead to denial-of-service (DoS) vulnerabilities if an attacker can trigger an unexpected error, and the application does not respond appropriately. ### 4.3 ProGuard/R8 Obfuscation **Standard:** Use ProGuard or R8 to obfuscate the code, making it more difficult for attackers to reverse engineer the application. **Why:** Obfuscation makes the code harder to understand and reverse engineer, hindering attackers attempting to analyze and exploit the application. **Do This:** * Enable ProGuard or R8 in the release build configuration. * Configure ProGuard or R8 to remove unused code and rename classes and methods. * Test the application thoroughly after enabling ProGuard or R8. **Don't Do This:** * Rely on obfuscation as the only security measure. * Disable ProGuard or R8 in release builds. * Exclude sensitive classes or methods from obfuscation. **Code Example: Enabling R8 in "gradle.properties"** """ android.enableR8=true """ **Anti-Pattern:** Relying solely on obfuscation without addressing underlying vulnerabilities provides a false sense of security, as determined attackers can often bypass obfuscation through reverse engineering techniques. By adhering to these security best practices, Kotlin Android developers can build robust and secure applications that protect sensitive data. These guidelines should be considered a living document, regularly updated to address evolving threats and emerging technologies.
# API Integration Standards for Kotlin Android This document outlines the coding standards and best practices for API integration in Kotlin Android applications. It aims to provide guidance for developers to build robust, maintainable, and performant Android applications that interact with backend services and external APIs. These standards are designed to be consistent with modern Kotlin and Android development approaches. ## 1. Architecture and Design ### 1.1. Layered Architecture **Standard:** Implement a layered architecture to separate concerns and improve maintainability. This typically includes: * **Data Layer:** Handles data retrieval and persistence (API calls, database interactions, etc.). * **Domain Layer:** Contains business logic and use cases. * **Presentation Layer (UI Layer):** Handles user interface and interaction logic (Activities, Fragments, Composable functions, ViewModels, etc.). * **Dependency Injection Layer (Optional but recommended):** Manages dependencies between layers. Use Hilt (recommended) or Koin. **Why:** Layered architecture promotes separation of concerns, making the codebase more modular and easier to test, maintain, and scale. **Do This:** """kotlin // Data Layer (Repository) class UserRepository(private val apiService: ApiService) { suspend fun getUser(userId: String): Result<User> { return try { val response = apiService.getUser(userId) if (response.isSuccessful) { Result.Success(response.body()!!) } else { Result.Error(Exception("API Error: ${response.code()}")) } } catch (e: Exception) { Result.Error(e) } } } // Domain Layer (UseCase) class GetUserUseCase(private val userRepository: UserRepository) { suspend operator fun invoke(userId: String): Result<User> { return userRepository.getUser(userId) } } // Presentation Layer (ViewModel) class UserViewModel( private val getUserUseCase: GetUserUseCase, savedStateHandle: SavedStateHandle // Use SavedStateHandle for persisting state across config changes ) : ViewModel() { private val _user = MutableStateFlow<Result<User>>(Result.Loading) val user: StateFlow<Result<User>> = _user.asStateFlow() val userId: String = savedStateHandle.get<String>("userId") ?: throw IllegalArgumentException("Missing user ID") init { loadUser() } private fun loadUser() { viewModelScope.launch { _user.value = getUserUseCase(userId) } } } """ **Don't Do This:** """kotlin // Anti-pattern: Mixing UI and API calls in the Activity/Fragment/Composable function class MainActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) // Network call directly in the Activity! BAD! CoroutineScope(Dispatchers.Main).launch { val apiService = Retrofit.Builder() .baseUrl("https://example.com/api/") .addConverterFactory(GsonConverterFactory.create()) .build() .create(ApiService::class.java) try { val response = apiService.getUser("123") if (response.isSuccessful) { // Update UI } else { // Handle error } } catch (e: Exception) { // Handle exception } } } } """ ### 1.2. Data Transfer Objects (DTOs) **Standard:** Use DTOs to represent the data received from APIs. Map these DTOs to domain models within the data layer. **Why:** DTOs decouple your application's internal data models from the API's data structure. This allows you to adapt to API changes without affecting the entire application and improves testability. **Do This:** """kotlin // API Response DTO data class UserDto( val id: String, val username: String, val email: String ) // Domain Model data class User( val id: String, val username: String, val email: String ) // Data Layer (Repository) class UserRepository(private val apiService: ApiService) { suspend fun getUser(userId: String): Result<User> { return try { val response = apiService.getUser(userId) if (response.isSuccessful) { val userDto = response.body()!! val user = User(userDto.id, userDto.username, userDto.email) // Mapping DTO to Domain Model Result.Success(user) } else { Result.Error(Exception("API Error: ${response.code()}")) } } catch (e: Exception) { Result.Error(e) } } } """ **Don't Do This:** """kotlin // Anti-pattern: Using the API response class directly in the UI layer data class UserDto( //This becomes part of the UI layer's direct dependency val id: String, val username: String, val email: String ) // ViewModel class UserViewModel(private val userRepository: UserRepository) : ViewModel() { private val _user = MutableLiveData<UserDto>() // Exposing DTO directly to the UI! BAD! val user: LiveData<UserDto> = _user fun loadUser(userId: String) { viewModelScope.launch { val result = userRepository.getUser(userId) if (result is Result.Success) { _user.value = result.data // Directly assigning API response to UI } else { // Handle error } } } } """ ### 1.3. Handling API Keys and Secrets **Standard:** Never hardcode API keys or secrets directly in your code. Use secure methods to store and access them, such as: * **Build Config Fields:** Use "buildConfigField" in your "build.gradle.kts" file to store API keys. These are compiled into the app and are more difficult to extract than resources. * **Secrets Gradle Plugin:** Use the "com.google.android.libraries.mapsplatform.secrets-gradle-plugin" to securely manage secrets from a "secrets.properties" file during build time. * **Backend-for-Frontend (BFF):** Consider using a BFF to proxy API calls and manage secrets on the server side. This reduces exposure of secrets to the mobile client. **Why:** Hardcoding API keys compromises the security of your application and can lead to unauthorized access to your API accounts. **Do This:** """kotlin // build.gradle.kts (Module: app level) plugins { id("com.android.application") id("org.jetbrains.kotlin.android") id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") //Secrets Gradle Plugin } android { buildTypes { release { buildConfigField("String", "API_KEY", "\"YOUR_API_KEY\"") // Build config field // ... } debug { buildConfigField("String", "API_KEY", "\"YOUR_API_KEY\"") // Build config field // ... } } //... } """ """kotlin //Accessing API Key (Kotlin) val apiKey = BuildConfig.API_KEY """ **secrets.properties:** """properties MAPS_API_KEY=YOUR_ACTUAL_MAPS_API_KEY """ **Don't Do This:** """kotlin // Anti-pattern: Hardcoding API Key val apiKey = "YOUR_API_KEY" // Never do this! """ ## 2. Retrofit and Networking ### 2.1. Retrofit Client **Standard:** Use Retrofit for making network requests. Configure the Retrofit client with appropriate settings, including: * **Base URL:** Define a constant for the base URL. * **Converter Factory:** Use "GsonConverterFactory" or "KotlinSerializationConverterFactory" (for Kotlinx Serialization). * **OkHttpClient:** Configure an "OkHttpClient" with timeouts, interceptors (for logging and authentication), and caching. * **Error Handling:** Use "try-catch" blocks or Kotlin's "Result" type to handle network errors gracefully. **Why:** Retrofit simplifies network requests, handles serialization/deserialization, and provides a clean, type-safe API. **Do This:** """kotlin import okhttp3.OkHttpClient import okhttp3.logging.HttpLoggingInterceptor import retrofit2.Retrofit import retrofit2.converter.gson.GsonConverterFactory import java.util.concurrent.TimeUnit object ApiClient { private const val BASE_URL = "https://api.example.com/" private val loggingInterceptor = HttpLoggingInterceptor().apply { level = HttpLoggingInterceptor.Level.BODY // Log request and response details } private val okHttpClient = OkHttpClient.Builder() .addInterceptor(loggingInterceptor) .connectTimeout(30, TimeUnit.SECONDS) //Set timeouts .readTimeout(30, TimeUnit.SECONDS) .writeTimeout(30, TimeUnit.SECONDS) .build() val retrofit: Retrofit = Retrofit.Builder() .baseUrl(BASE_URL) .addConverterFactory(GsonConverterFactory.create()) //Use Gson or Kotlinx Serialization .client(okHttpClient) .build() } // API Interface interface ApiService { @GET("users/{userId}") suspend fun getUser(@Path("userId") userId: String): retrofit2.Response<UserDto> } // Usage val apiService = ApiClient.retrofit.create(ApiService::class.java) """ **Don't Do This:** """kotlin // Anti-pattern: Creating a new Retrofit instance for every request fun getUser(userId: String): UserDto? { val retrofit = Retrofit.Builder() // Creating a new Retrofit instance every time! BAD! .baseUrl("https://api.example.com/") .addConverterFactory(GsonConverterFactory.create()) .build() val apiService = retrofit.create(ApiService::class.java) //... } """ ### 2.2. Coroutines and Flow **Standard:** Use Kotlin Coroutines and Flow for asynchronous network requests. Retrofit supports suspending functions, which can be called directly from coroutines. Use "flow" builder to emit data from the network layer to the UI. **Why:** Coroutines provide a concise and efficient way to handle asynchronous operations, making your code more readable and maintainable. Flow provides a reactive stream of data. **Do This:** """kotlin import kotlinx.coroutines.flow.Flow import kotlinx.coroutines.flow.flow import kotlinx.coroutines.Dispatchers interface ApiService { @GET("users/{userId}") suspend fun getUser(@Path("userId") userId: String): Response<UserDto> } class UserRepository(private val apiService: ApiService) { fun getUserFlow(userId: String): Flow<Result<User>> = flow { emit(Result.Loading) // Emit Loading state try { val response = apiService.getUser(userId) if (response.isSuccessful) { val userDto = response.body()!! val user = User(userDto.id, userDto.username, userDto.email) emit(Result.Success(user)) // Emit Success with data } else { emit(Result.Error(Exception("API Error: ${response.code()}"))) //Emit Error } } catch (e: Exception) { emit(Result.Error(e)) //Emit Exception } }.flowOn(Dispatchers.IO) // Run on I/O thread } // ViewModel to collect the Flow class UserViewModel(private val userRepository: UserRepository) : ViewModel() { private val _userState = MutableStateFlow<Result<User>>(Result.Loading) val userState: StateFlow<Result<User>> = _userState.asStateFlow() fun loadUser(userId: String) { viewModelScope.launch { userRepository.getUserFlow(userId) .collect { result -> _userState.value = result } } } } """ **Don't Do This:** """kotlin // Anti-pattern: Using callbacks for API calls fun getUser(userId: String, callback: (UserDto?) -> Unit) { // Avoid callbacks! val apiService = ApiClient.retrofit.create(ApiService::class.java) val call = apiService.getUser(userId) call.enqueue(object : Callback<UserDto> { override fun onResponse(call: Call<UserDto>, response: Response<UserDto>) { callback(response.body()) } override fun onFailure(call: Call<UserDto>, t: Throwable) { callback(null) } }) } """ ### 2.3. Error Handling with "Result" **Standard:** Use Kotlin's "Result" type (or a custom "Result" sealed class) to represent the outcome of API calls. This allows you to handle success, error, and loading states in a type-safe manner. **Why:** "Result" type forces you to handle both success and error scenarios preventing crashes and providing a better user experience. **Do This:** """kotlin // Define a Result sealed class if you're not targeting Android 13+ (which includes Result) sealed class Result<out T> { data class Success<out T>(val data: T) : Result<T>() data class Error(val exception: Exception) : Result<Nothing>() object Loading : Result<Nothing>() } //Api Service & Repository (as shown in previous examples using Result type throughout) """ **Don't Do This:** """kotlin // Anti-pattern: Returning null on error fun getUser(userId: String): UserDto? { // Returning null on error!BAD! try { val response = apiService.getUser(userId) return response.body() } catch (e: Exception) { return null // Returning null } } """ ### 2.4. Pagination and List Handling **Standard:** Implement pagination when dealing with large datasets from APIs. Use appropriate query parameters to request data in chunks. Display a loading indicator while fetching more data. **Why:** Pagination improves performance and prevents your app from crashing due to excessive memory usage. It also provides a better user experience. **Do This:** """kotlin // API Interface interface ApiService { @GET("users") suspend fun getUsers( @Query("page") page: Int, @Query("limit") limit: Int ): Response<List<UserDto>> } // Repository class UserRepository(private val apiService: ApiService) { suspend fun getUsers(page: Int, limit: Int): Result<List<User>> { return try { val response = apiService.getUsers(page, limit) if (response.isSuccessful) { //... map to User objects } //... } //... } } // ViewModel (using Paging 3 library) class UserViewModel(private val userRepository: UserRepository) : ViewModel() { val userFlow: Flow<PagingData<User>> = Pager( config = PagingConfig(pageSize = 20, enablePlaceholders = false), pagingSourceFactory = { UserPagingSource(userRepository) } ).flow.cachedIn(viewModelScope) } // PagingSource class UserPagingSource( private val userRepository: UserRepository ) : PagingSource<Int, User>() { override suspend fun load(params: LoadParams<Int>): LoadResult<Int, User> { val pageNumber = params.key ?: 1 val pageSize = params.loadSize return when (val result = userRepository.getUsers(pageNumber, pageSize)) { is Result.Success -> { val users = result.data LoadResult.Page( data = users, prevKey = if (pageNumber == 1) null else pageNumber - 1, nextKey = if (users.isEmpty()) null else pageNumber + 1 ) } is Result.Error -> { LoadResult.Error(result.exception) } Result.Loading -> { LoadResult.Error(Exception("Unexpected loading state")) // Handle loading within paging source is odd but possible } } } override fun getRefreshKey(state: PagingState<Int, User>): Int? { return state.anchorPosition?.let { anchorPosition -> state.closestPageToPosition(anchorPosition)?.prevKey?.plus(1) ?: state.closestPageToPosition(anchorPosition)?.nextKey?.minus(1) } } } //In the UI use collectAsState(context = Dispatchers.IO.asExecutor()) to display paginated data """ **Don't Do This:** """kotlin // Anti-pattern: Fetching all data at once suspend fun getAllUsers(): List<UserDto> { // Fetching all users at once! BAD! val response = apiService.getAllUsers() return response.body() ?: emptyList() } """ ## 3. Data Caching and Offline Support ### 3.1. Caching Strategies **Standard:** Implement caching strategies to improve performance and provide offline support. Consider using: * **In-memory caching:** Cache frequently accessed data in memory using "LruCache" or similar mechanisms. * **Disk-based caching:** Use Room database to cache data persistently on disk. * **Network caching:** Use OkHttp's built-in caching mechanisms by configuring "Cache-Control" headers. **Why:** Caching reduces network requests, improves app responsiveness, and allows users to access data even when offline. **Do This:** """kotlin // OkHttp Cache Configuration val cacheSize = 10 * 1024 * 1024L // 10MB val cache = Cache(context.cacheDir, cacheSize) """ """kotlin // Add Interceptor for cache control val okHttpClient = OkHttpClient.Builder() .cache(cache) .addInterceptor { chain -> var request = chain.request() request = if (isNetworkAvailable(context)) request.newBuilder().header("Cache-Control", "public, max-age=" + 60).build() // Cache for 1 minute when online else request.newBuilder().header("Cache-Control", "public, only-if-cached, max-stale=" + 60 * 60 * 24 * 7).build() // Cache for 7 days when offline chain.proceed(request) } .build() // Function to check network availability (implement this based on ConnectivityManager) fun isNetworkAvailable(context: Context): Boolean { // Implementation... return false; } """ **Don't Do This:** """kotlin // Anti-pattern: Not implementing any caching suspend fun getUser(userId: String): UserDto? { // No caching! val response = apiService.getUser(userId) return response.body() } """ ### 3.2. Offline Data Synchronization **Standard:** Implement a mechanism to synchronize offline data with the backend when the device comes back online. Use a background service or WorkManager to handle synchronization. **Why:** Offline synchronization ensures data consistency and provides a seamless user experience even with intermittent network connectivity. **Do This:** """kotlin // WorkManager for syncing data in the background class SyncWorker(appContext: Context, workerParams: WorkerParameters) : CoroutineWorker(appContext, workerParams) { private val userRepository = UserRepository(/*...*/); override suspend fun doWork(): Result { return try { val unsyncedData = // get unsynced data userRepository.syncData(unsyncedData) // Call API to sync Result.success() } catch (e: Exception) { Result.retry() // Retry the work later } finally { //Cleanup work } } } // Schedule the worker val syncRequest = PeriodicWorkRequestBuilder<SyncWorker>(1, TimeUnit.HOURS) // Sync every hour .build() WorkManager.getInstance(context).enqueueUniquePeriodicWork( "syncData", ExistingPeriodicWorkPolicy.KEEP, // Or REPLACE syncRequest ) """ ## 4. Security Considerations ### 4.1. HTTPS **Standard:** Always use HTTPS for all API communication to encrypt data in transit. **Why:** HTTPS protects sensitive data from eavesdropping and tampering. **Do This:** """kotlin // Correct: Using HTTPS private const val BASE_URL = "https://api.example.com/" // Use HTTPS """ **Don't Do This:** """kotlin // Incorrect: Using HTTP private const val BASE_URL = "http://api.example.com/" // Never use HTTP """ ### 4.2. Input Validation **Standard:** Validate all user input and API responses to prevent injection attacks and data corruption. **Why:** Input validation prevents malicious data from being processed by your application or the backend. **Do This:** """kotlin fun validateUserId(userId: String): Boolean { // Check if userId is valid (e.g., alphanumeric, length) return userId.matches(Regex("[a-zA-Z0-9]+")) && userId.length in 5..20 } """ ### 4.3. Data Encryption **Standard:** Encrypt sensitive data stored locally using appropriate encryption algorithms. **Why:** Data encryption protects data even if the device is compromised. ## 5. Testing ### 5.1. Unit Testing **Standard:** Write unit tests for your data layer (repositories, use cases) to verify that API calls are made correctly, data is parsed correctly, and errors are handled properly. Mock the "ApiService" using Mockito or Mockk. **Why:** Unit tests ensure the reliability of your API integration logic. **Do This:** """kotlin import io.mockk.coEvery import io.mockk.mockk import kotlinx.coroutines.runBlocking import org.junit.Assert.assertEquals import org.junit.Test class UserRepositoryTest { @Test fun "getUser should return success when API call is successful"() = runBlocking { // Arrange val mockApiService = mockk<ApiService>() // Create a Mock ApiService coEvery { mockApiService.getUser("123") } returns Response.success(UserDto("123", "test", "test@example.com")) // mock the result val userRepository = UserRepository(mockApiService) // Act val result = userRepository.getUser("123") // Assert assert(result is Result.Success) assertEquals("123", (result as Result.Success).data.id) } } """ ## 6. Monitoring and Logging ### 6.1. Logging **Standard:** Use a logging framework (Timber) to log API requests, responses, and errors. Log relevant information such as request URLs, response codes, and error messages. However, be very careful not to log sensitive data such as passwords or API keys. **Why:** Logging helps you monitor API usage, debug issues, and identify performance bottlenecks. **Do This:** """kotlin import timber.log.Timber //Add Timber to application class class MyApplication : Application() { override fun onCreate() { super.onCreate() if (BuildConfig.DEBUG) { //Only log in debug builds. Timber.plant(Timber.DebugTree()) } } } //Logging within the app. Timber.d("API Request: GET /users/123") Timber.i("API Response: %s", response.body()) Timber.e(e, "API Error") """ This coding standards document provides a comprehensive guide to API integration in Kotlin Android applications. Adhering to these standards will help developers build robust, maintainable, and secure applications that effectively interact with backend services and external APIs.
# Code Style and Conventions Standards for Kotlin Android This document outlines the code style and conventions standards for Kotlin Android development. Adhering to these guidelines will ensure code consistency, readability, maintainability, and optimal performance. It is designed to be used by developers and AI coding assistants to create high-quality Kotlin Android applications. ## 1. General Formatting Consistent formatting is crucial for code readability. Kotlin's syntax allows for flexibility, but adhering to standards helps maintain clarity. ### 1.1. Indentation and Whitespace * **Do This:** Use 4 spaces for indentation. Avoid tabs. Configure your IDE to automatically convert tabs to spaces. * **Don't Do This:** Rely on default IDE settings; they may not always match team conventions. """kotlin // Correct indentation fun calculateSum(a: Int, b: Int): Int { val sum = a + b return sum } // Incorrect indentation (using tabs or inconsistent spaces) fun calculateSum(a: Int, b: Int): Int { val sum = a + b return sum } """ * **Why This Matters:** Consistent indentation greatly enhances readability, making it easier to understand the code's structure and logic. * **Modern Approach:** Modern IDEs and linters can enforce indentation rules automatically. Use them! ### 1.2. Line Length * **Do This:** Limit lines to a maximum of 120 characters. This improves readability, especially on smaller screens. * **Don't Do This:** Allow lines to become excessively long, requiring horizontal scrolling. """kotlin // Good: Line length within limits val user = User( firstName = "John", lastName = "Doe", email = "john.doe@example.com" ) // Bad: Line exceeds limits (difficult to read) val user = User(firstName = "John", lastName = "Doe", email = "john.doe@example.com", address = "123 Main St, Anytown, USA") """ * **Why This Matters:** Readable code is easier to maintain and debug. Long lines reduce readability. * **Modern Approach:** Use automatic line wrapping features in your IDE to break long lines logically. ### 1.3. Vertical Whitespace * **Do This:** Use blank lines to separate logical blocks of code within functions or classes. Add blank lines between functions and classes. Use sparingly to avoid overly sparse code. * **Don't Do This:** Bunch all code together without any separation, or overuse blank lines. """kotlin // Good use of vertical whitespace fun processData(data: List<Int>): Int { // Filter out negative numbers val positiveData = data.filter { it > 0 } // Calculate the sum of positive numbers val sum = positiveData.sum() return sum } // Bad: No whitespace (hard to read) fun processData(data: List<Int>): Int {val positiveData = data.filter { it > 0 }val sum = positiveData.sum()return sum} """ * **Why This Matters:** Proper vertical whitespace improves visual structure, making code easier to scan and understand. ### 1.4. Braces * **Do This:** Use K&R style braces: opening brace on the same line as the statement, closing brace on its own line. * **Don't Do This:** Opening brace on the next line unless required by language semantics, inconsistent brace style. """kotlin // Correct brace style fun performAction(value: Int) { if (value > 0) { println("Positive value") } else { println("Non-positive value") } } """ * **Why This Matters:** Consistency in brace style improves readability and reduces visual clutter. ## 2. Naming Conventions Consistent and meaningful naming is essential for code maintainability and understandability. ### 2.1. General Naming * **Do This:** Use clear, descriptive names that accurately reflect the purpose of the variable, function, or class. * **Don't Do This:** Use single-letter variable names (except in loops), cryptic abbreviations, or names that don't reflect the purpose. * **Classes:** Use PascalCase (e.g., "UserManager", "DataParser"). * **Functions/Methods:** Use camelCase (e.g., "calculateTotal", "getUserDetails"). * **Variables:** Use camelCase (e.g., "userName", "orderTotal"). * **Constants:** Use UPPER_SNAKE_CASE (e.g., "MAX_VALUE", "DEFAULT_TIMEOUT"). * **Interfaces:** Use PascalCase, often prefixed with "I" (e.g., "IUserRepository"). (Note: While some prefer no "I" prefix, consistency within a project is paramount). """kotlin // Good naming class UserManager { fun getUserDetails(userId: String): User { // ... } companion object { const val MAX_USERS = 100 } } // Bad naming class UM { // cryptic fun gUD(id: String): User { //abbreviations // ... } companion object { const val MU = 100 // unclear } } """ * **Why This Matters:** Meaningful names improve code readability and reduce the cognitive load required to understand the code. * **Modern Approach:** Leverage IDE auto-completion to avoid typos when using long, descriptive names. ### 2.2. Android-Specific Naming * **Do This:** Follow Android's naming conventions for resources and UI elements. * **Don't Do This:** Use generic or confusing names for Android resources. * **Layout Files:** Use snake_case with a descriptive prefix (e.g., "activity_main.xml", "item_user_list.xml"). * **IDs for Views:** Use camelCase with a descriptive prefix based on View type (e.g., "userNameTextView", "submitButton"). * **Drawables:** Use snake_case with a descriptive prefix (e.g., "ic_launcher_background.xml", "button_background.xml"). """xml <!-- Good Naming --> <TextView android:id="@+id/userNameTextView" android:layout_width="wrap_content" android:layout_height="wrap_content" /> <Button android:id="@+id/submitButton" android:layout_width="wrap_content" android:layout_height="wrap_content" /> <!-- Bad Naming --> <TextView android:id="@+id/tv1" // Undescriptive android:layout_width="wrap_content" android:layout_height="wrap_content" /> <Button android:id="@+id/btn1" // Undescriptive abbreviation android:layout_width="wrap_content" android:layout_height="wrap_content" /> """ * **Why This Matters:** Android's naming conventions ensure consistency across the project and ease collaboration. * **Modern Approach:** Use data binding and view binding to reduce boilerplate and make view references more type-safe, further emphasizing clear and descriptive IDs. ### 2.3. Package Naming * **Do This:** Use reverse domain name notation for package names (e.g., "com.example.myapp"). * **Don't Do This:** Use generic package names like "com.app" or "org.". """kotlin // Good package name package com.example.myapp.ui.home // Bad package name package com.app.ui.home // Not specific """ * **Why This Matters:** Package naming prevents naming conflicts and ensures unique identification of the application. ## 3. Stylistic Consistency and Best Practices Maintaining a consistent style improves readability and minimizes errors. ### 3.1. Null Safety * **Do This:** Utilize Kotlin's null safety features to prevent NullPointerExceptions ("?", "!!", "?:", "let", "run", "also", "apply"). Prefer safe calls ("?.") and elvis operator ("?:") over force unwrapping ("!!"). * **Don't Do This:** Rely on Java-style null checks. Overuse force unwrapping ("!!") without proper justification. """kotlin // Good: Safe calls and Elvis operator fun getUsername(user: User?): String { return user?.name ?: "Guest" // If user is null, return "Guest" } // Good: let block for null check and chained operations user?.let { it.address?.let { address -> println("User lives in ${address.city}") } } // Bad: Force unwrapping without null check (potential NPE) fun getUsername(user: User?): String { return user!!.name // Risky if user is null } // Bad: Java-style null check (less concise) fun getUsername(user: User?): String { if (user != null) { return user.name } else { return "Guest" } } """ * **Why This Matters:** NullPointerExceptions are a common source of errors in Android apps. Kotlin's null safety features provide a more robust and concise way to handle nullability. * **Modern Approach:** Consider using "@Nullable" and "@NonNull" annotations (from "androidx.annotation") for interoperability with Java code to improve nullability awareness. ### 3.2. Data Classes * **Do This:** Use data classes for classes that primarily hold data. * **Don't Do This:** Use regular classes for data-holding purposes, which require manual implementation of "equals()", "hashCode()", and "toString()". """kotlin // Good: Data class for representing user data data class User(val id: String, val name: String, val email: String) // Bad: Regular class (needs manual implementation of data-related methods) class UserClass(val id: String, val name: String, val email: String) { override fun equals(other: Any?): Boolean { // Manual implementation } override fun hashCode(): Int { // Manual implementation } override fun toString(): String { // Manual implementation } } """ * **Why This Matters:** Data classes automatically generate useful methods like "equals()", "hashCode()", "toString()", and "copy()", reducing boilerplate and improving code conciseness. * **Modern Approach:** Data classes are especially useful with Kotlin's destructuring declarations. ### 3.3. Immutability * **Do This:** Prefer immutable data structures (e.g., "val" properties, "List", "Set", "Map") over mutable ones ("var" properties, "MutableList", "MutableSet", "MutableMap") whenever possible. * **Don't Do This:** Unnecessarily use mutable data structures, leading to potential state management issues. """kotlin // Good: Immutable list val users: List<User> = listOf(User("1", "John", "john@example.com")) // Bad: Mutable list when immutability is sufficient var users: MutableList<User> = mutableListOf(User("1", "John", "john@example.com")) """ * **Why This Matters:** Immutable data structures simplify state management, reduce the risk of bugs, and improve thread safety. * **Modern Approach:** Use Kotlin's "copy()" function (available in data classes) to create modified copies of immutable objects. ### 3.4. Extension Functions * **Do This:** Use extension functions to add functionality to existing classes without modifying their source code. Use them judiciously to enhance code clarity and avoid polluting class APIs. * **Don't Do This:** Overuse extension functions, leading to code that is difficult to understand and maintain. """kotlin // Good: Extension function to validate email format fun String.isValidEmail(): Boolean { return android.util.Patterns.EMAIL_ADDRESS.matcher(this).matches() } //Usage val email = "test@example.com" if(email.isValidEmail()) { println("Valid Email") } // Bad: Overusing extension functions for core class functionalities fun Context.showToast(message: String) { // Could simply use Toast.makeText inside the class Toast.makeText(this, message, Toast.LENGTH_SHORT).show() } """ * **Why This Matters:** Extension functions promote code reusability and make code more expressive. They allow you to add utility functions to existing classes without inheritance or modification. * **Modern Approach:** Use extension functions to add functionality to Android framework classes (e.g., "Context", "View") for a more Kotlin-idiomatic way of interacting with the framework. ### 3.5. Coroutines * **Do This:** Utilize Kotlin Coroutines for asynchronous programming to avoid blocking the main thread. Use structured concurrency ("CoroutineScope") to manage coroutine lifecycles, especially in Android components (Activities, Fragments, ViewModels). Use "viewModelScope" (from "androidx.lifecycle:lifecycle-viewmodel-ktx") within ViewModels. * **Don't Do This:** Use "AsyncTask" for new code, or perform long-running operations directly on the main thread, leading to UI freezes. Abuse "GlobalScope" without proper lifecycle management. """kotlin // Good: Using viewModelScope for Coroutine lifecycle management class MyViewModel : ViewModel() { fun fetchData() { viewModelScope.launch { val data = withContext(Dispatchers.IO) { // Perform network request here on a background thread delay(1000) // Simulate network delay "Data from network" } // Update UI on the main thread _data.value = data } } private val _data = MutableLiveData<String>() val data: LiveData<String> = _data } // Bad: Blocking the main thread fun fetchData() { Thread.sleep(5000) // Simulate network call (BLOCKS UI) // Update UI (this will cause ANR if the delay is too long) } // Avoid: GlobalScope without lifecycle awareness fun fetchData() { GlobalScope.launch { // Potential memory leaks if not managed properly // ... } } """ * **Why This Matters:** Coroutines simplify asynchronous programming, improve app responsiveness, and prevent ANR (Application Not Responding) errors. Structured concurrency ensures proper resource management and avoids memory leaks. * **Modern Approach:** Use the "kotlinx.coroutines" library (included in most Android projects) and its integration with Android Architecture Components (like "viewModelScope") for streamlined asynchronous tasks. Use "Flow" for asynchronous streams of data. ### 3.6. Resource Management * **Do This:** Properly manage resources (e.g., file streams, network connections, database cursors) by closing them in "finally" blocks or using Kotlin's "use" function. "use" guarantees the resource is closed whether the code completes normally or throws an exception. * **Don't Do This:** Leak resources by not closing them, leading to performance issues or app crashes. """kotlin import java.io.BufferedReader import java.io.FileReader // Good: Using 'use' to automatically close the reader fun readFile(filePath: String): String? { return try { BufferedReader(FileReader(filePath)).use { reader -> reader.readText() } } catch (e: Exception) { e.printStackTrace() null } } // Bad: Not closing the reader (resource leak) fun readFileBad(filePath: String): String? { val reader = BufferedReader(FileReader(filePath)) return reader.readText() // Reader might not be closed, especially if an exception occurs. } """ * **Why This Matters:** Proper resource management prevents memory leaks, improves performance, and ensures app stability. * **Modern Approach:** Use "use" for any resource that implements the "Closeable" interface. ### 3.7. Dependency Injection * **Do This:** Use a dependency injection framework (e.g., Hilt, Dagger, Koin) to manage dependencies and improve testability. Hilt is the recommended dependency injection library for Android as of the latest versions. * **Don't Do This:** Manually create and manage dependencies throughout the codebase, leading to tightly coupled code and difficulty in testing. """kotlin // Good: Using Hilt for dependency injection (define module) @Module @InstallIn(SingletonComponent::class) object AppModule { @Singleton @Provides fun provideUserRepository(): UserRepository { return UserRepositoryImpl() } } // Good: Inject dependencies using @Inject class MyViewModel @Inject constructor(private val userRepository: UserRepository) : ViewModel() { // ... } """ * **Why This Matters:** Dependency injection decouples components, making code more modular, testable, and maintainable. Hilt simplifies dependency injection in Android apps by providing a standard way to incorporate DI. * **Modern Approach:** Hilt streamlines DI setup and reduces boilerplate compared to Dagger. Consider Koin for smaller projects where simplicity is paramount. ### 3.8. View Binding and Data Binding * **Do This:** Prefer View Binding or Data Binding over "findViewById" for accessing views in layouts. Use Data Binding when two-way binding or complex UI logic is required. Use View Binding when only access to the view is needed. * **Don't Do This:** Use "findViewById" directly, as it's error-prone and requires manual casting. """kotlin // Good: Using View Binding private lateinit var binding: ActivityMainBinding override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) binding = ActivityMainBinding.inflate(layoutInflater) setContentView(binding.root) binding.userNameTextView.text = "Hello, View Binding!" // Type-safe access } //Alternative Good: Using Data Binding private lateinit var binding: ActivityMainBinding override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) binding = DataBindingUtil.setContentView(this, R.layout.activity_main) binding.user = User("1", "DataBinding User", "") // Pass data to layout binding.lifecycleOwner = this // Let layout observe LiveData } """ """xml <!-- Example used with Data Binding --> <layout xmlns:android="http://schemas.android.com/apk/res/android" xmlns:app="http://schemas.android.com/apk/res-auto"> <data> <variable name="user" type="com.example.myapp.User" /> </data> <TextView android:id="@+id/userNameTextView" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="@{user.name}" /> <!-- Use binding expression --> </layout> """ * **Why This Matters:** View Binding and Data Binding provide type-safe access to views, reduce boilerplate code, and improve performance, especially compared to "findViewById". Data Binding enables declarative UI updates and facilitates the Model-View-ViewModel (MVVM) architecture. * **Modern Approach:** Consider using Kotlin Android Extensions (view binding) plugin, but be aware that it is deprecated. Migration to ViewBinding is recommended. ### 3.9. Companion Objects * **Do This:** Use companion objects to hold constants, utility functions, or factory methods that are associated with a class but don't require an instance of the class. * **Don't Do This:** Overuse companion objects, especially for code that logically belongs to the class itself. """kotlin // Good: Companion object for constants class UserManager { companion object { const val MAX_USERS = 100 } fun createUser() { if (userCount < MAX_USERS) { // ... } } var userCount = 0 } """ * **Why This Matters:** Companion objects provide a clear and organized way to group related constants and functions within a class, improving code structure. ### 3.10. Sealed Classes * **Do This:** Use sealed classes to represent a limited set of possible subtypes or states. They're particularly useful for representing the states of a UI or the result of an operation. * **Don't Do This:** Use enums when sealed classes offer more flexibility (e.g., enums can't hold state). Use regular classes when sealed classes more accurately represent the problem domain. """kotlin // Good: Sealed class for representing result sealed class Result<out T : Any> { data class Success<out T : Any>(val data: T) : Result<T>() data class Error(val exception: Exception) : Result<Nothing>() object Loading : Result<Nothing>() } fun handleResult(result: Result<String>) { when (result) { is Result.Success -> println("Success: ${result.data}") is Result.Error -> println("Error: ${result.exception}") Result.Loading -> println("Loading...") } } """ * **Why This Matters:** Sealed classes enable exhaustive "when" statements, ensuring that all possible subtypes or states are handled. This improves code safety and maintainability. The compiler will warn you if you do not handle all possible subtypes in a "when" expression. ## 4. Kotlin Specific Features in Android ### 4.1. Use Scope Functions Appropriately * **Do This:** Understand the differences between "let", "run", "with", "apply", and "also", and use them accordingly to improve code readability and conciseness. * "let": Executes a block of code on a non-null object and returns the result of the block. Useful for null-safe operations and transforming data. * "run": Executes a block of code on an object and returns the result of the block. Similar to "let" but is called directly on the object: "obj.run { ... }". Useful for configuring data or performing calculations. * "with": Executes a block of code on an object (passed as an argument to "with") and returns the result of the block. Useful when you want to operate on the properties of an object within a concise scope: "with(obj) { ... }". * "apply": Executes a block of code on an object and returns the object itself. Useful for configuring an object and returning it in a fluent style. * "also": Executes a block of code with the object as an argument and returns the object itself. Useful for performing side effects (e.g., logging) without changing the object. * **Don't Do This:** Use them randomly or interchangeably, which can make the code confusing. """kotlin // Example using let for null-safe operation val name: String? = "John" val length = name?.let { println("Name is not null") it.length // Return value } ?: 0 // Example using apply for object configuration val textView = TextView(context).apply { text = "Hello" textSize = 16f setTextColor(Color.BLACK) } //Example using also for logging fun processData(data:String) : String { return data.also{ println("Data is $it") }.uppercase() } """ * **Why This Matters:** Scope functions allow writing more concise and expressive code, which can increase readability and reduce boilerplate. ### 4.2. Use Properties Instead of Getters and Setters * **Do This:** Prefer Kotlin's property syntax over explicit getter and setter methods. * **Don't Do This:** Create Java-style getter and setter methods unless you need custom logic within them. """kotlin // Good: Using properties class Person { var name: String = "" get() = field.uppercase() //backing field set(value) { field = value } } // Bad: Java-style getters and setters class PersonJavaStyle { private var name: String = "" fun getName(): String { return name } fun setName(name: String) { this.name = name } } """ * **Why This Matters:** Properties provide a more concise and Kotlin-idiomatic way to access and modify object state. ### 4.3. Use "when" Expressions * **Do This:** Prefer "when" expressions over "if-else" chains when handling multiple conditions, especially with sealed classes or enums. * **Don't Do This:** Use deeply nested "if-else" statements, which can be harder to read and maintain. """kotlin // Good: Using when expression fun describe(obj: Any): String = when (obj) { 1 -> "One" "Hello" -> "Greeting" is Long -> "Long" else -> "Unknown" } """ ## 5. Performance Considerations ### 5.1. Avoid Unnecessary Object Creation * **Do This:** Minimize object creation, especially in performance-critical sections of code (e.g., inside loops or in "onDraw"). * **Don't Do This:** Create temporary objects unnecessarily, which can lead to increased memory consumption and garbage collection pauses. Use object pooling for frequently used objects. ### 5.2. Use Sparse Arrays * **Do This:** Use "SparseArray", "SparseBooleanArray", or "SparseIntArray" instead of "HashMap" for mapping integers to objects when memory efficiency is a concern, specifically when targeting older Android API levels. As of newer API levels, "HashMap" has become highly optimized and the performance differences have narrowed. * **Don't Do This:** Use "HashMap" blindly for integer keys, especially where memory is constrained. ### 5.3. Optimize Layouts * **Do This:** Optimize layouts by reducing the view hierarchy, using "ConstraintLayout" effectively, and avoiding overdraw. * **Don't Do This:** Create complex and deeply nested layouts, which can impact rendering performance. ## 6. Security Best Practices ### 6.1. Input Validation * **Do This:** Validate all user inputs to prevent injection attacks, buffer overflows, and other security vulnerabilities. Use parameterized queries for database interactions. * **Don't Do This:** Trust user inputs without validation. Construct SQL queries by concatenating strings. ### 6.2. Data Encryption * **Do This:** Encrypt sensitive data at rest and in transit. Use appropriate encryption algorithms and secure key management practices. Consider using Jetpack Security library. * **Don't Do This:** Store sensitive data in plain text. Hardcode encryption keys in the code. ### 6.3. Permissions * **Do This:** Request only the necessary permissions and explain why they are needed to the user. Request permissions at runtime when possible. Follow the principle of least privilege. * **Don't Do This:** Request all permissions upfront without justification. Store sensitive information without proper authorization. ### 6.4. Secure Coding Practices * **Do This:** Be aware of common security vulnerabilities (e.g., injection attacks, cross-site scripting, insecure data storage) and follow secure coding practices to mitigate them. Use static analysis tools to identify potential vulnerabilities. * **Don't Do This:** Ignore security warnings from IDEs or linters. Use deprecated or insecure APIs.