6    Software dokumentieren

Dokumentation ist ein unverzichtbarer, aber oft ungeliebter Bestandteil der Softwareentwicklung. Die Dokumentation einer Applikation lässt sich in verschiedene Ebenen unterteilen. Sie unterscheidet sich in ihrem Zielpublikum und ihrer Nähe zum Quellcode.

In diesem Kapitel konzentrieren wir uns auf die Dokumentationsarten mit einem direkten Bezug zum Quellcode, also der API-Dokumentation, Klassen- und Funktionsdokumentation und Inline-Kommentare. Diese Arten der Dokumentation werden hauptsächlich zum Übermitteln von Informationen zwischen Mitgliedern des Entwicklungsteams verwendet. Dabei gehen die Meinungen stark auseinander, welche Teile des Quellcodes wie dokumentiert werden sollen.

Die verschiedenen Lager reichen von »Jeder Block im Code muss dokumentiert werden« bis hin zu »Mein Code ist selbsterklärend, Dokumentation ist unnötig«. Wir wollen einen pragmatischen Mittelweg wählen: Alle öffentlichen Schnittstellen, mit denen andere Entwickler zu tun haben, sollen dokumentiert werden. Zusätzlich dazu sollen komplexe Codestellen mit erklärenden Kommentaren versehen werden.

Herausforderungen beim Dokumentieren

Dokumentation zählt, wie auch das automatisierte Testen, nicht unbedingt zu den Lieblingsdisziplinen von Entwicklern. Wie beim Testen gibt es auch bei der Dokumentation eine Reihe von Herausforderungen, denen Sie mithilfe von KI-Unterstützung begegnen können. Dazu zählen unter anderem:

6.1    Inline-Dokumentation

Inline-Dokumentation umfasst alle Kommentare und Dokumentation, die direkt im Quellcode einer Applikation eingebettet sind. Diese Art der Dokumentation hilft, den Code direkt im Lesefluss verständlicher zu machen.

Inline-Kommentare verwenden Sie, wenn Sie Codeabschnitte erklären möchten. Sie kommen vor allem bei komplexen und schwer verständlichen Codeabschnitten zum Einsatz. Ein typisches Beispiel sind Codestellen, die nicht intuitiv sind. Wenn Sie einen Teil der Businesslogik so implementiert haben, dass sie zwar funktioniert, jedoch nicht dem Codestandard Ihrer Applikation entspricht, sollten Sie dies kommentieren. Würden Sie den Code entsprechend anpassen, würde die Logik nicht mehr wie gewünscht funktionieren. Um zu vermeiden, dass Sie oder eine andere Person zu einem späteren Zeitpunkt diese Änderung dennoch vornimmt, können Sie einen Kommentar hinterlassen.

Wie nahezu alles in der Softwareentwicklung hat auch die Inline-Dokumentation sowohl Vor- als auch Nachteile. Je nachdem, in welchem Kontext Sie sie einsetzen, kommen diese Aspekte mehr oder weniger zum Tragen.

Ein Vorteil der Inline-Dokumentation ist, dass Sie sie unmittelbar einsetzen und damit komplexe Codestellen direkt erklären können. Die Nachteile sind hauptsächlich die reduzierte Lesbarkeit des Codes und eine potenzielle Überkommentierung.

Da die Nachteile der Inline-Dokumentation deutlich überwiegen, sollten Sie sie eher sparsam einsetzen und nur an wirklich erklärungsbedürftigen Stellen verwenden. Den übrigen Quellcode Ihrer Applikation sollten Sie so selbsterklärend formulieren, dass keine Inline-Kommentare erforderlich sind.

Beispiel für Inline-Dokumentation

Als konkretes Beispiel für das sinnvolle Einfügen von Inline-Kommentaren nutzen wir eine Funktion, die die n-te Fibonacci-Zahl berechnet. Der Code der Funktion sieht ohne Kommentare folgendermaßen aus:

const fibonacci = (n: number): number => {
  if (n < 0) {
    throw new Error("n must be a non-negative number");
  }
  if (n === 0) return 0;
  if (n === 1) return 1;
  let a = 0;
  let b = 1;
  for (let i = 2; i <= n; i++) {
    const temp = a + b;
    a = b;
    b = temp;
  }
  return b;
};

Der einzige Hinweis auf den Zweck der Funktion ist ihr Name. Aus dem Code und den verkürzten Variablennamen ergibt sich auf den ersten Blick nicht, was die Funktion macht. Also bitten wir im nächsten Schritt ChatGPT, erklärende Inline-Kommentare einzufügen:

Prompt: Please add inline comments to the following function to explain what is happening.

(Code der Funktion)

Sure, here is the function with inline comments explaining each step:

const fibonacci = (n: number): number => {
  // Check if the input is a negative number and throw an 
  // error if it is
  if (n < 0) {
    throw new Error("n must be a non-negative number");
  }

  // If n is 0, the Fibonacci number is 0
  if (n === 0) return 0;

  // If n is 1, the Fibonacci number is 1
  if (n === 1) return 1;

  // Initialize the first two Fibonacci numbers
  let a = 0;
  let b = 1;

  // Loop from 2 to n to calculate the nth Fibonacci number
  for (let i = 2; i <= n; i++) {
    // Calculate the next Fibonacci number
    const temp = a + b;
    // Update the previous two Fibonacci numbers
    a = b;
    b = temp;
  }

  // Return the nth Fibonacci number
  return b;
};

Mit diesen erklärenden Kommentaren, die den Zweck fast jeder Zeile erklären, wird der Algorithmus schnell verständlich. Zeilen, die zusammengehören und mit einem Kommentar erklärt werden, hat die KI auch hier zusammengefasst und jeweils mit einer Leerzeile vom Rest getrennt. Diese Art der Dokumentation hilft Ihnen bei der Erstellung von Algorithmen, damit diese für andere Personen oder Sie selbst in der Zukunft direkt im Code erklärt werden. Sie können diese Art der KI-Unterstützung aber auch verwenden, wenn Sie Code warten müssen, den Sie von anderen Personen übernommen haben. Bevor Sie sich die Bedeutung des Codes mühevoll selbst erschließen, können Sie ihn sich auf diese Weise erklären lassen und diese Erklärung als Bestandteil des Codes in die Versionskontrolle übernehmen.

Für einen sinnvollen Inline-Kommentar benötigt die KI den Quellcode, den Sie kommentieren möchten, und eine Anweisung, was genau Sie erreichen möchten. In diesem Fall war die Aufgabenstellung klar, da die komplette Funktion Schritt für Schritt kommentiert werden sollte. Sie können jedoch auch nur einzelne Kommentare einfügen lassen. Hier ein Beispiel für die Berechnung eines rabattierten Preises.

function calculateDiscount(price, discount) {
  const validDiscount = discount > 100 ? 100 : discount;
  
  const finalPrice = price - (price * (validDiscount / 100));

  return finalPrice;
}

Hier können Sie ChatGPT bitten, Ihnen zu erklären, was die Zeile mit validDiscount macht, und auch gleich einen Kommentar einfügen lassen.

Prompt: What does the line with validDiscount do? Please add an inline comment.

(Code der Funktion)

The line with validDiscount is checking if the discount value is greater than 100. If it is, it sets validDiscount to 100, effectively capping the discount at 100%. Otherwise, it keeps the discount as is. This ensures that the discount doesn’t exceed 100%, which would not make sense in a typical pricing scenario.

function calculateDiscount(price, discount) {
  // Ensure the discount does not exceed 100% 
  // by capping it at 100
  const validDiscount = discount > 100 ? 100 : discount;
  ...
}

More details …

Mit solchen Fällen werden Sie deutlich häufiger zu tun haben als mit der Kommentierung jeder einzelnen Zeile. In diesem Fall müssen Sie Ihrer KI jedoch auch mehr Informationen geben, was genau Sie erwarten.

Inline-Dokumentation sollten Sie eher sparsam benutzen, da sie die Lesbarkeit des Quellcodes nicht in jedem Fall verbessert. Deutlich häufiger kommt die Funktions- und Klassendokumentation zum Einsatz.