Documentation Basics für Android-Projekte

In Android-Projekten entsteht Wartbarkeit nicht nur durch sauberen Kotlin-Code, klare Compose-UIs oder gute Tests. Du brauchst auch eine kurze, verlässliche Projektdokumentation, die erklärt, wie das Projekt gestartet wird, welche Architekturentscheidungen gelten und welche Regeln beim Ändern des Codes wichtig sind. Genau darum geht es bei Documentation Basics: Du dokumentierst Setup und wichtige Entscheidungen so, dass du selbst, dein Team oder ein späterer Junior-Dev nicht raten müssen.

Was ist das?

Documentation Basics bedeutet im Android-Kontext: Du hältst die wichtigsten Informationen zu einem Projekt an einem gut auffindbaren Ort fest. Meist beginnt das mit einem README.md im Repository. Dort beschreibst du, was die App macht, welche Voraussetzungen nötig sind, wie du sie lokal baust, wie Tests laufen und welche Projektstruktur relevant ist. Ergänzend können Architektur-Notizen dazukommen, zum Beispiel als kurze Markdown-Dateien unter docs/architecture/.

Der mentale Rahmen ist wichtig: Dokumentation ersetzt nicht den Code. Sie erklärt, wie du den Code zuverlässig benutzt und weiterentwickelst. Ein gutes README beantwortet nicht jede Detailfrage, sondern die Fragen, die beim Einstieg fast immer auftauchen: Welche Android-Studio-Version brauche ich? Welche JDK-Version wird erwartet? Welche Gradle-Tasks sind wichtig? Gibt es API-Keys, Produktvarianten, Compose-Previews, lokale Testdaten oder besondere Build-Flavors?

Für Android-Lernende ist das Thema eng mit moderner Entwicklung verbunden. Wenn du mit Kotlin, Jetpack Compose, ViewModel, Navigation, Room, Retrofit, Coroutines, Flow oder Tests arbeitest, reicht es nicht, einzelne APIs zu kennen. Du musst auch verstehen, warum das Projekt so aufgebaut ist. Architektur-Notizen helfen dabei. Sie erklären zum Beispiel, warum UI-State im ViewModel liegt, warum Datenzugriff in einem Repository gekapselt wird oder warum die App eine klare Trennung zwischen UI-, Domain- und Data-Schicht nutzt.

Der Nutzen zeigt sich im Alltag: Neue Entwickler starten schneller, Fehler beim Setup werden seltener, Code-Reviews werden präziser und Architekturentscheidungen gehen nicht in Chatverläufen verloren. Das ist besonders wichtig, weil Android-Projekte viele bewegliche Teile haben: Gradle, Manifest, App-Komponenten, Ressourcen, Compose-UI, Lifecycle, Tests, Build-Varianten und Qualitätsanforderungen für Geräte, Bildschirmgrößen und Android-Versionen.

Wie funktioniert es?

Gute Projektdokumentation funktioniert wie eine Landkarte mit klarer Reihenfolge. Zuerst kommt der Einstieg: Was ist dieses Projekt, und wie bringst du es auf deinem Rechner zum Laufen? Danach folgen tägliche Arbeitsabläufe: Wie startest du die App, wie führst du Unit-Tests und instrumentierte Tests aus, wie prüfst du Lint, und welche Regeln gelten für Pull Requests? Danach kommen Architektur-Notizen: Welche Entscheidungen wurden bewusst getroffen, und welche Alternativen wurden verworfen?

Ein README sollte kurz genug bleiben, damit es gelesen wird. Lange Erklärungen gehören eher in eigene Dateien, die vom README verlinkt werden. Eine gute Struktur ist zum Beispiel: Projektüberblick, Voraussetzungen, Setup, Build und Test, Architekturüberblick, wichtige Konventionen, bekannte Stolperfallen. So findet ein Anfänger zuerst die praktischen Schritte, während ein Junior-Dev später die Architekturregeln nachlesen kann.

Bei Android ist das Setup besonders kritisch. Ein fehlender Hinweis zur JDK-Version, zu local.properties, zu benötigten SDK-Komponenten oder zu geheimen API-Keys kann dafür sorgen, dass ein Projekt auf einem neuen Rechner nicht baut. Auch Compose-Projekte profitieren von klaren Hinweisen: Welche Compose-BOM wird verwendet? Gibt es Preview-Daten? Werden UI-Tests lokal oder nur in CI erwartet? Welche Mindest-SDK und Ziel-SDK gelten?

Architektur-Notizen sollten Entscheidungen dokumentieren, nicht nur den aktuellen Zustand beschreiben. Ein häufiger Fehler ist ein Satz wie: “Wir verwenden MVVM.” Das ist zu dünn. Besser ist: “UI-State wird im ViewModel gehalten, Composables bleiben möglichst zustandsarm, Daten kommen über Repository-Schnittstellen, und Flows werden im ViewModel in sichtbaren UI-State umgewandelt.” Das gibt dir eine konkrete Prüfbasis für Code-Reviews.

Auch Tests gehören in die Documentation Basics. Du musst nicht jeden Test erklären, aber du solltest beschreiben, welche Testarten im Projekt vorgesehen sind. Unit-Tests prüfen Kotlin-Logik schnell auf der JVM. Instrumentierte Tests laufen auf einem Gerät oder Emulator. Compose-UI-Tests prüfen Interaktion und Darstellung. Wenn dein README die wichtigsten Kommandos und Erwartungen nennt, kann ein Team Qualitätsregeln wirklich einhalten.

Wichtig ist außerdem die Pflege. Dokumentation ist kein einmaliges Nebenprodukt beim Projektstart. Jede größere Änderung kann eine Dokumentationsfrage auslösen: Ändert sich das Setup? Kommt ein neues Modul dazu? Wird eine Architekturregel verändert? Gibt es neue Tests, neue Build-Varianten oder neue Release-Schritte? Wenn ja, sollte die Dokumentation im selben Pull Request aktualisiert werden. Sonst wird sie langsam unzuverlässig.

In der Praxis

Stell dir vor, du baust eine kleine Compose-App mit einer Aufgabenliste. Die App nutzt ein ViewModel, ein Repository und lokale Daten. Ein neuer Entwickler soll das Projekt klonen, starten und eine kleine Änderung sicher testen können. Ein passendes README könnte so aufgebaut sein:

# TaskList Android

Kleine Android-App mit Kotlin, Jetpack Compose und lokaler Datenhaltung.

## Voraussetzungen

- Android Studio Koala oder neuer
- JDK 17
- Android SDK mit API 35
- Emulator oder Gerät mit Android 8.0 oder neuer

## Setup

1. Repository klonen.
2. Projekt in Android Studio öffnen.
3. Gradle-Sync ausführen.
4. Falls vorhanden, `local.properties` nicht einchecken.
5. App-Konfiguration über Build-Varianten prüfen.

## Build und Tests

- Debug-Build: `./gradlew assembleDebug`
- Unit-Tests: `./gradlew testDebugUnitTest`
- Instrumentierte Tests: `./gradlew connectedDebugAndroidTest`
- Lint: `./gradlew lintDebug`

## Architektur

Die UI wird mit Compose gebaut. Composables zeigen Zustand an und senden Events nach außen.
ViewModels halten UI-State und rufen Use-Cases oder Repositories auf.
Repositories kapseln Datenquellen und liefern Kotlin Flow oder suspend-Funktionen.
Android-Framework-Code bleibt möglichst an den Rändern der App.

## Stolperfallen

- Keine API-Keys in Git einchecken.
- Keine Datenbankoperationen direkt in Composables ausführen.
- Neue Architekturentscheidungen in `docs/architecture/` dokumentieren.
- Bei neuen Features passende Unit- oder UI-Tests ergänzen.

Dazu passt eine kurze Architektur-Notiz, die eine konkrete Entscheidung festhält:

# Architektur-Notiz: UI-State im ViewModel

Datum: 2026-04-25

## Kontext

Die App nutzt Jetpack Compose. Mehrere Screens laden Daten asynchron und müssen Ladezustand,
Fehler und Inhalte stabil anzeigen.

## Entscheidung

Jeder Screen erhält ein eigenes ViewModel. Das ViewModel stellt einen immutable UI-State bereit.
Composables lesen diesen State und senden Nutzeraktionen als Events zurück.

## Konsequenzen

Composables bleiben leichter testbar und enthalten weniger Geschäftslogik.
Asynchrone Datenflüsse werden im ViewModel gesammelt.
UI-Tests prüfen Interaktion, Unit-Tests prüfen State-Änderungen im ViewModel.

Auch ein kleines Kotlin-Beispiel kann eine Architekturregel stützen:

data class TaskListUiState(
    val isLoading: Boolean = false,
    val tasks: List<Task> = emptyList(),
    val errorMessage: String? = null
)

class TaskListViewModel(
    private val repository: TaskRepository
) : ViewModel() {

    private val _uiState = MutableStateFlow(TaskListUiState())
    val uiState: StateFlow<TaskListUiState> = _uiState.asStateFlow()

    fun loadTasks() {
        viewModelScope.launch {
            _uiState.value = TaskListUiState(isLoading = true)

            runCatching {
                repository.observeTasks().first()
            }.onSuccess { tasks ->
                _uiState.value = TaskListUiState(tasks = tasks)
            }.onFailure {
                _uiState.value = TaskListUiState(
                    errorMessage = "Aufgaben konnten nicht geladen werden."
                )
            }
        }
    }
}

Die Dokumentation muss nicht jeden Codepfad erklären. Sie soll die Regel sichtbar machen: Der Screen liest uiState, das ViewModel steuert Ladezustand und Fehler, das Repository liefert Daten. Wenn ein Pull Request plötzlich Netzwerkaufrufe direkt in einem Composable ausführt, kannst du im Review auf die Architektur-Notiz verweisen. Das macht Kritik sachlicher, weil sie sich auf eine dokumentierte Entscheidung stützt.

Eine praktische Entscheidungsregel lautet: Dokumentiere alles, was ein neuer Entwickler nicht sicher aus dem Code ableiten kann, bevor er das Projekt baut oder sinnvoll ändert. Dazu gehören Setup-Schritte, externe Abhängigkeiten, lokale Konfiguration, Modulgrenzen, Teststrategie und Architekturentscheidungen mit Folgen für neue Features. Dokumentiere dagegen nicht jede Klasse in Prosa. Klassennamen, Typen und Tests sollten bereits viel erklären.

Eine typische Stolperfalle ist veraltete Dokumentation. Sie ist oft schlimmer als gar keine, weil sie falsche Sicherheit erzeugt. Wenn im README noch ./gradlew test steht, das Projekt aber mehrere Module und Varianten hat, verliert ein Anfänger Zeit mit falschen Annahmen. Deshalb gehört zur Definition of Done für relevante Änderungen ein kurzer Check: Muss das README angepasst werden? Muss eine Architektur-Notiz ergänzt werden? Muss ein Testbefehl aktualisiert werden?

Eine zweite Stolperfalle ist zu allgemeine Dokumentation. Sätze wie “Wir schreiben sauberen Code” helfen nicht. Besser sind überprüfbare Regeln: “Neue Repository-Methoden bekommen Unit-Tests”, “UI-State wird als immutable data class modelliert”, “Secrets werden nicht eingecheckt”, “Neue Screens erhalten mindestens eine Preview mit Beispielzustand”. Solche Regeln lassen sich im Code-Review prüfen.

Du kannst dein Verständnis üben, indem du ein bestehendes Android-Projekt nimmst und aus Sicht einer neuen Person liest. Kannst du es ohne Rückfragen bauen? Findest du die Testbefehle? Erkennst du die wichtigsten Architekturgrenzen? Wenn nicht, schreibe die fehlenden Informationen in ein README oder in eine kurze Notiz. Danach lässt du einen anderen Entwickler die Schritte ausführen oder prüfst sie selbst in einem frischen Klon. So merkst du schnell, ob deine Dokumentation praktisch trägt.

Fazit

Documentation Basics sind kein Zusatz für große Teams, sondern ein Grundwerkzeug für wartbare Android-Projekte. Du erklärst knapp, wie Setup, Build, Tests und Architekturentscheidungen funktionieren, damit Änderungen nicht auf Vermutungen beruhen. Prüfe das aktiv: Klone dein Projekt frisch, führe die dokumentierten Gradle-Tasks aus, lies die Architektur-Notizen beim nächsten Code-Review und ergänze fehlende Informationen direkt im passenden Pull Request.