Code so erklaeren, dass andere damit arbeiten koennen

1. Was ist Entwicklerdokumentation?

Entwicklerdokumentation ist nicht einfach "viel Text". Sie ist eine Hilfe fuer Menschen, die den Code lesen, benutzen, erweitern oder reparieren muessen. Das kann dein Team sein, dein zukuenftiges Ich oder eine Person, die neu ins Projekt kommt.

2. Zielgruppe: Fuer wen schreibst du?

Dokumentation muss zur Zielgruppe passen. Lernende brauchen mehr Erklaerung. Erfahrene Entwickler brauchen schnelle Orientierung. Ein Team braucht klare Regeln.

3. README: Die Startseite eines Projekts

Die wichtigste Dokumentation ist meistens die README.md. Sie ist die erste Datei, die man in einem Repository liest.

# Flutter Counter App

Kurze Beschreibung:
Diese App erweitert den Standard-Counter um mehrere Buttons.

## Lernziele
- Flutter-Projekt verstehen
- Widgets auslagern
- Parameter an Widgets uebergeben
- State veraendern

## Projekt starten
[bash]
flutter pub get
flutter run
[/bash]

## Wichtige Dateien
- lib/main.dart: Einstiegspunkt der App
- lib/widgets/counter_button.dart: Wiederverwendbarer Button
- pubspec.yaml: Abhaengigkeiten

Eine gute README beantwortet zuerst die wichtigsten Fragen. Details koennen spaeter kommen.

4. Markdown-Grundlagen

README-Dateien werden oft in Markdown geschrieben. Markdown ist eine einfache Schreibweise fuer Ueberschriften, Listen, Code und Links.

5. Code-Kommentare: Wann sind sie sinnvoll?

Kommentare sind gut, wenn sie eine Entscheidung oder einen schwierigen Zusammenhang erklaeren. Sie sind weniger gut, wenn sie nur wiederholen, was der Code sowieso sagt.

void withdraw(double amount) {
  // Geschaeftsregel: Das Konto darf nicht ins Minus gehen.
  if (amount > balance) {
    return;
  }

  balance -= amount;
}

6. DartDoc-Kommentare mit ///

In Dart nutzt du ///, um Klassen, Methoden und Felder fuer Entwickler zu dokumentieren. Diese Kommentare koennen von Tools ausgewertet werden.

/// Speichert Punkte fuer eine Lernaufgabe.
///
/// Ein Score ist immutable. Aenderungen erzeugen ein neues Objekt.
class Score {
  /// Aktuelle Punktzahl.
  final int value;

  const Score(this.value);

  /// Erstellt einen neuen Score mit zusaetzlichen Punkten.
  Score add(int points) {
    return Score(value + points);
  }
}

DartDoc sollte nicht jede Kleinigkeit erklaeren. Dokumentiere vor allem oeffentliche Klassen, wichtige Methoden, Parameter und Rueckgabewerte.

7. Dokumentiere Parameter und Rueckgabewerte

Wenn eine Methode nicht sofort klar ist, sollte die Dokumentation sagen, was die Parameter bedeuten und was zurueckgegeben wird.

/// Prueft, ob eine Person alt genug ist.
///
/// [age] ist das Alter in Jahren.
/// Gibt `true` zurueck, wenn [age] mindestens 18 ist.
bool isAdult(int age) {
  return age >= 18;
}

In DartDoc kannst du Parameternamen mit eckigen Klammern markieren, zum Beispiel [age].

8. Ordnerstruktur dokumentieren

Bei groesseren Projekten hilft eine kurze Erklaerung der Ordner. Das verhindert, dass neue Dateien irgendwo landen.

lib/
  main.dart                 Einstiegspunkt
  models/                   Datenklassen
    user.dart
    learning_task.dart
  widgets/                  Wiederverwendbare UI-Bausteine
    counter_button.dart
  screens/                  Ganze Seiten
    home_screen.dart
  services/                 Logik fuer API, Dateien oder Datenquellen

Wichtig ist nicht, dass jede Datei lang erklaert wird. Wichtig ist, dass man die Struktur versteht.

9. Commands dokumentieren

Ein Projekt sollte klare Befehle enthalten. Besonders bei Dart und Flutter sind Commands wichtig.

10. Entscheidungen dokumentieren

Manchmal ist nicht der Code schwer, sondern die Frage: Warum wurde es so gemacht? Dafuer kannst du kurze Entscheidungsnotizen schreiben.

## Entscheidung: Immutable User-Modell

Wir nutzen ein immutable User-Modell mit `final` Feldern und `copyWith`.

Grund:
- Weniger unerwartete Seiteneffekte
- Besser nachvollziehbare State-Aenderungen
- Passend fuer Flutter-State-Management

Alternative:
Mutable User mit Settern.

Warum nicht:
Setters machen schwerer sichtbar, wo sich Daten veraendern.

11. Fehler und bekannte Grenzen dokumentieren

Gute Dokumentation verschweigt nicht, was noch fehlt. Offene Punkte helfen beim Weiterarbeiten.

## Bekannte Grenzen

- Die App speichert Daten noch nicht dauerhaft.
- Es gibt noch keine Validierung fuer leere Namen.
- Der Counter kann aktuell unter 0 fallen.

## Naechste Schritte

- Eingabevalidierung ergaenzen
- Lokale Speicherung pruefen
- Tests fuer Counter-Logik schreiben

12. Gute Dokumentation ist kurz, aber konkret

Dokumentation soll nicht alles doppelt sagen. Sie soll die Stellen erklaeren, die fuer Verstaendnis, Nutzung und Wartung wichtig sind.

13. Dokumentation planen

Auch Dokumentation kann man planen. Erst sammelst du Fragen, dann schreibst du die Antworten in eine sinnvolle Reihenfolge.

Starte Dokumentation

Beschreibe Projektziel in 2 Saetzen
Liste Lernziele auf
Notiere Start-Commands
Beschreibe wichtige Ordner
Erklaere zentrale Klassen
Dokumentiere bekannte Grenzen
Schreibe naechste Schritte

Pruefe:
  Kann eine neue Person das Projekt starten?
  Versteht sie die wichtigsten Dateien?
  Weiss sie, was noch fehlt?