Informatik · Klasse 10 · Software-Projektmanagement · 2. Halbjahr

Dokumentation und Clean Code

Die Schülerinnen und Schüler schreiben lesbaren und wartbaren Programmcode und erstellen technische Dokumentationen.

• KMK Bildungsstandards
• KMK: STD.02
• KMK: STD.08

Über dieses Thema

Dokumentation und Clean Code sind die Grundlagen für nachhaltige Softwareentwicklung. Schüler lernen, dass Code öfter gelesen als geschrieben wird und deshalb für Menschen optimiert sein muss. Dies entspricht den KMK-Standards zur Dokumentation und zur Anwendung von Programmierkonventionen.

Die Schüler beschäftigen sich mit sprechenden Variablennamen, kleinen Funktionen und dem Verzicht auf 'Spaghetti-Code'. Sie erfahren, wie technische Dokumentation (z.B. Javadoc) hilft, Software auch nach Monaten noch zu verstehen oder im Team zu teilen. Dies fördert die Disziplin und das Bewusstsein für Qualität, die über das reine Funktionieren hinausgeht. In einer vernetzten Welt ist lesbarer Code die Voraussetzung für erfolgreiche Open-Source-Zusammenarbeit.

Durch Peer-Reviews, bei denen Schüler den Code ihrer Mitschüler lesen und bewerten müssen, wird die Bedeutung von Klarheit und Struktur sofort offensichtlich.

Leitfragen

1. Warum schreiben wir Code primär für Menschen, nicht für Maschinen?
2. Was macht eine gute technische Dokumentation aus?
3. Wie verhindern wir „Spaghetti-Code"?

Lernziele

• Analysieren Sie die Auswirkungen von schlechter Code-Formatierung und unklaren Variablennamen auf die Lesbarkeit und Wartbarkeit von Software.
• Bewerten Sie die Qualität von technischer Dokumentation anhand definierter Kriterien wie Vollständigkeit, Genauigkeit und Verständlichkeit.
• Erstellen Sie eine kurze technische Dokumentation für eine einfache Funktion oder Klasse unter Anwendung von Konventionen wie Javadoc.
• Entwerfen Sie Refactoring-Strategien zur Verbesserung von Code-Abschnitten, die als 'Spaghetti-Code' identifiziert wurden.
• Erklären Sie die Prinzipien von Clean Code und deren Bedeutung für die Teamarbeit und die langfristige Projektgesundheit.

Bevor es losgeht

Grundlagen der Programmierung (Variablen, Datentypen, Kontrollstrukturen)

Warum: Grundlegende Kenntnisse über die Bausteine der Programmierung sind notwendig, um über deren Struktur und Lesbarkeit sprechen zu können.

Einführung in Funktionen und Methoden

Warum: Das Verständnis von Funktionen ist die Basis, um über deren Größe, Zweck und die Vermeidung von Komplexität zu diskutieren.

Schlüsselvokabular

Clean Code	Ein Programmierstil, der darauf abzielt, Code nicht nur funktional, sondern auch lesbar, verständlich und wartbar zu machen.
Spaghetti-Code	Umgangssprachlicher Begriff für schlecht strukturierte, schwer nachvollziehbare Programmabläufe mit vielen Sprüngen und Abhängigkeiten.
Javadoc	Ein Dokumentationsgenerator für Java, der aus speziellen Kommentaren im Quellcode automatisch API-Dokumentationen erstellt.
Refactoring	Der Prozess der Umstrukturierung von bestehendem Computercode, ohne das externe Verhalten zu ändern, um die Lesbarkeit und Wartbarkeit zu verbessern.
Sprechende Variablennamen	Variablenbenennung, die ihren Zweck oder Inhalt klar und eindeutig beschreibt, anstatt kryptische Abkürzungen zu verwenden.

Vorsicht vor diesen Fehlvorstellungen

Häufige Fehlvorstellung

Kommentare machen schlechten Code gut.

Was Sie stattdessen lehren sollten

Schüler versuchen oft, wirre Logik durch viel Text zu erklären. Durch Refactoring-Übungen lernen sie, dass eine Umstrukturierung des Codes meist besser ist als ein langer Kommentar.

Häufige Fehlvorstellung

Dokumentation schreibt man ganz am Ende.

Was Sie stattdessen lehren sollten

Oft wird sie vergessen. Eine Übung, bei der Schüler ihren eigenen Code von vor vier Wochen ohne Doku verstehen müssen, zeigt, dass Dokumentation ein begleitender Prozess sein muss.

Ideen für aktives Lernen

Forschungskreis: Code-Detektive

Schüler erhalten zwei Versionen desselben Programms: Eine mit kryptischen Namen und eine in 'Clean Code'. Sie müssen unter Zeitdruck eine Änderung vornehmen und vergleichen, wo es schneller ging.

40 Min.·Kleingruppen

Museumsgang: Die Dokumentations-Wand

Gruppen erstellen Plakate mit Best Practices für Clean Code (z.B. 'Don't repeat yourself'). Sie hängen Beispiele für 'schlechten' und 'guten' Code daneben auf.

35 Min.·Ganze Klasse

Ich-Du-Wir (Denken-Austauschen-Vorstellen): Kommentare vs. Lesbarer Code

Schüler diskutieren: 'Sollte man jede Zeile kommentieren oder den Code so schreiben, dass er sich selbst erklärt?'. Partner erarbeiten Regeln für sinnvolle Kommentare.

20 Min.·Partnerarbeit

Bezüge zur Lebenswelt

• Softwareentwickler bei großen Technologieunternehmen wie Google oder Microsoft arbeiten täglich mit Clean Code Prinzipien, um komplexe Systeme wie Betriebssysteme oder Webanwendungen wartbar zu halten. Ihre Dokumentation ist entscheidend für die Zusammenarbeit in global verteilten Teams.
• Open-Source-Projekte wie der Linux-Kernel oder die Mozilla Firefox-Entwicklung sind auf gut dokumentierten und lesbaren Code angewiesen. Freiwillige weltweit tragen dazu bei, indem sie Code-Reviews durchführen und Verbesserungsvorschläge machen.

Ideen zur Lernstandserhebung

Gegenseitige Bewertung

Die Schüler erhalten anonymisierte Code-Schnipsel ihrer Mitschüler. Sie sollen auf einer Checkliste bewerten: Sind die Variablennamen aussagekräftig? Sind die Funktionen kurz und fokussiert? Gibt es Kommentare, wo sie nötig sind? Sie geben eine schriftliche Begründung für mindestens eine Verbesserung.

Lernstandskontrolle

Auf einem Zettel notieren die Schüler zwei konkrete Vorteile von Clean Code für die Softwareentwicklung und nennen ein Beispiel für eine gute technische Dokumentation, die sie kennen oder sich vorstellen können.

Diskussionsfrage

Diskutieren Sie in Kleingruppen: Warum ist es für einen Anfänger schwieriger, guten Code zu schreiben als nur funktionierenden Code? Welche Rolle spielt die Dokumentation, wenn ein Projekt nach einem Jahr wieder aufgenommen wird?

Häufig gestellte Fragen

Was bedeutet 'Clean Code'?

Es ist ein Ansatz, Code so einfach, lesbar und wartbar wie möglich zu schreiben. Ziel ist es, dass andere Entwickler (oder man selbst in der Zukunft) den Code sofort verstehen.

Warum sind Variablennamen wie 'x' oder 'data' schlecht?

Weil sie nichts über den Inhalt oder Zweck aussagen. Namen wie 'benutzerAlter' oder 'rechnungsBetrag' machen den Code selbsterklärend und reduzieren Fehler.

Wie unterstützt aktives Lernen das Verständnis von Clean Code?

Clean Code lernt man am besten durch das Lesen fremden Codes. In Peer-Review-Sitzungen erleben Schüler den Frust über unlesbare Programme und den Stolz auf elegante Lösungen. Dieser soziale Austausch motiviert weitaus mehr zur Einhaltung von Standards als theoretische Regeln. Aktive Refactoring-Aufgaben helfen zudem, den Blick für saubere Strukturen zu schärfen.

Was ist Javadoc?

Ein Werkzeug für Java, das aus speziellen Kommentaren im Quellcode automatisch eine übersichtliche HTML-Dokumentation für andere Programmierer erstellt.