Und was ist mit Kommentaren?

Der Autor eines der bekanntesten Bücher über Clean Code schreibt dazu:

Comments do not make up for bad code - Robert C. Martin (Kommentare machen schlechten Code nicht wett)

Kommentare haben ihren Zweck und ihre Aufgabe. Dazu muss man unterscheiden, um welche Kommentare es sich handelt:

Dokumentationskommentare

Dokumentationskommentare beschreiben nicht den Code. Sie liefern eine Zusammenfassung eines Programms (oder später auch einer Methode). Sie sollen verstanden werden ohne den Code zu sehen. Sie bilden für zukünftige Programmiererinnen und Anwenderinnen eine Entscheidungshilfe, ob das Programm (oder die Methode) verwendet werden soll. Durch die Angabe von Autor und Datum bekommt man zusätzliche Informationen über die Verantwortlichkeit und ob man überhaupt die richtige Version verwendet.

Zeilenkommentare, die nicht offensichtliche Werte erklären

Manchmal werden für die Initialisierung nicht offensichtliche Werte verwendet. Warum z.B. werden die ersten 2 Variablen in unserem Beispiel-Programm mit 1 initialisiert? Dies sollte jedenfalls durch Kommentare erklärt werden. Dadurch können auch Hinweise auf Schwächen im Programm gegeben werden. Dass wir die Anzahl der leeren Felder gleich einmal mit 1 annehmen und davon ausgehen, dass auf dem ersten Feld sowieso keine Körner liegen, ist z.B. nicht optimal und sollte in einer Überarbeitung verbessert werden.

Zeilenkommentare, die noch offene Punkte in einem Programm zeigen - TODO

Meistens entstehen Programmcodes über einen längeren Zeitraum. Manchmal kann man sich auch nicht gleich um alle Probleme gleichzeitig kümmern, sondern man muss Prioritäten setzen. Deshalb ist es empfehlenswert, offene Punkte mit einem TODO (abgekürzt aus dem englischen there is something to do) versehen. Viele Programmieroberflächen unterstützen diese Kommentare und heben sie gesondert hervor. In einer endgültigen Abgabe sollten sie natürlich nicht mehr vorkommen.

Zeilenkommentare, als "Überschriften"

Auch ein normaler Text profitiert von Absätzen und Überschriften. Er verleiht einem Text Struktur und man kann ihn dadurch leichter lesen. Mit Leerzeilen und Zeilenkommentaren kann man dies auch für Code erreichen. Nach einer Reihe von zusammengehörenden Anweisungen, wie z.B. den Variablen-Deklarationen und -Initialisierungen kann man durch eine leere Zeile zeigen, dass man zu einem neuen Teil des Programmcodes übergeht. Verstärken kann man dies noch, in dem man diesem neuen Code-Teil eine Art "Überschrift" gibt, die beschreibt, was im nächsten Programmteil zu erwarten ist. Dadurch bekommt das Programm zwar insgesamt mehr Zeilen, aber auch mehr Struktur. Diese Struktur ist für einen menschlichen Leser leichter zu erfassen.

Der folgende Programmcode zeigt alle besprochenen Punkte beispielhaft auf:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

/**
 * Der Hamster läuft in Blickrichtung, bis er auf ein Hindernis stößt.
 * Währenddessen sammelt er Körner ein und zählt dabei, die Anzahl 
 * der Felder insgesamt, der leeren Felder und der Felder mit Körnern
 * sowie die Anzahl der gesammelten Körner
 * @author Lisa Vittori
 * @version 2025-01-19
 */
void main()
 {
    int anzahlFelderGesamt = 1; // 1 wegen Feld auf dem der Hamster steht
    int anzahlLeereFelder = 1; // das Hamster-Start-Feld zählt als leeres Feld
    int anzahlFelderMitKorn = 0
;
    int anzahlKoerner = 0
;
    // TODO: Erstes Feld überprüfen und anzahlLeereFelder mit 0 starten lassen
    
    // nach vor gehen, bis zu einem Hindernis
    while
(vornFrei()) {
        vor();
        anzahlFelderGesamt++;
        
        // Entscheidung zwischen leeren Feldern und Feldern mit Körnern
        if
(!kornDa()) {
            anzahlLeereFelder++;
        }
        else
 {
            anzahlFelderMitKorn++;
            
            // alle Körner nehmen
            while
(kornDa()) {
                nimm();
                anzahlKoerner++;
            }
        }
    }
    
    schreib("Körner: " + anzahlKoerner + ", Felder gesamt: "
 + 
        anzahlFelderGesamt + ", Felder mit Körnern: "
 + 
        anzahlFelderMitKorn + ", leere Felder "
 + anzahlLeereFelder);
}

Ergänze folgende Zusammenfassung und beantworte die Fragen:

• Kreuze an, welche Aufgaben ein Dokumentationskommentar hat:

  liefert eine Struktur für den Quellcode
  beschreibt zusammenfassend die Funktion des Programms
  gibt zusätzliche Hinweise über den/die Ersteller*in
  bietet Informationen über die Version
  beschreibt den Code

• Kreuze an, welche Aufgaben Zeilen- (oder Blockkommentare) haben:

  beschreiben, warum gewisse Werte oder Funktionsweisen eingesetzt werden
  strukturieren den Quellcode
  sollen jede einzelne Codezeile beschreiben
  verwendet man anstelle von guten Variablennamen
  bieten die Möglichkeit, offene Probleme im Quellcode als TODO-Einträge festzuhalten