6.4    Veraltete Dokumentation

Es gibt wenig, was schlimmer ist als veraltete Dokumentation. Hatten Sie einmal in einer Applikation das Problem, dass Sie sich nicht auf die Dokumentation, also beispielsweise den Kommentarblock für eine Funktion, verlassen konnten, werden Sie in Zukunft mehr Zeit in die Recherche investieren und im Zweifel auch einen zusätzlichen Blick in den Code werfen. Die Implementierung einer Erweiterung wird also mehr Zeit in Anspruch nehmen.

Wie entsteht veraltete Dokumentation? In der Regel nicht durch böswillige Personen, die andere aufs Glatteis führen wollen, sondern meist aus Zeitdruck oder weil die Aktualisierung der Dokumentation schlicht vergessen wurde. Was bleibt, ist jedoch der Vertrauensverlust, und damit verliert die Dokumentation erheblich an Wert.

Arbeiten Sie selbst an der Aktualisierung einer Funktion, können Sie sich von KI-Werkzeugen helfen lassen und die Dokumentation automatisiert aktualisieren lassen. Als Beispiel für einen solchen Workflow soll uns eine Funktion fetchUserData dienen. Sie wurde ursprünglich so implementiert, dass Sie ihr die ID eines Users und eine Callback-Funktion übergeben. Die Funktion selbst lädt die Daten von einem Webserver und ruft anschließend die Callback-Funktion auf. Durch einen Umbau ist die Funktion nun als async-Funktion implementiert. Sie akzeptiert nur noch die ID des Benutzers und gibt ein Promise-Objekt mit den geladenen Userdaten zurück. Die Funktionsdokumentation verweist jedoch noch auf die alte Implementierung. Im Code sieht das dann wie folgt aus:

/**
 * Fetches user data from the server using the Fetch API.
 *
 * This function sends a GET request to the server to retrieve 
 * user data based on the provided user ID. The response is 
 * expected to be in JSON format.
 *
 * @param {number} userId The ID of the user whose data 
 *                        is to be fetched.
 * @param {function} callback A callback function that will 
 *                            be called with the user data.
 *                            The callback should accept two 
 *                            parameters: an error (if any) or 
 *                            null if the request was successful 
 *                            and the user data.
 *
 * @return {void}
 */
async function fetchUserData(userId: number) {
  const response = await fetch(`/api/users/${userId}`);
  if (!response.ok) {
    throw new Error('Failed to fetch user data');
  }
  return response.json();
}

Die Beschreibung der Funktion stimmt zwar noch, die Erklärung der Parameter und des Rückgabewerts ist jedoch falsch. Um das Problem zu lösen, können Sie beispielsweise wieder auf die GitHub-Copilot-Integration von VS Code zurückgreifen und folgenden Prompt absetzen:

Prompt: Please update the documentation for the fetchUserData function.

/**
 * Fetches user data from the server.
 *
 * @param userId - The ID of the user to fetch data for.
 * @returns A promise that resolves to the user data.
 * @throws An error if the request fails.
 */
async function fetchUserData(userId: number) {
  const response = await fetch(`/api/users/${userId}`);
  if (!response.ok) {
    throw new Error("Failed to fetch user data");
  }
  return response.json();
}

Was hier direkt auffällt, ist, dass der Copilot deutlich in die Struktur des Kommentars eingegriffen hat. Die ursprüngliche, ausführliche Beschreibung der Funktion wurde entfernt, und auch die Typen der Parameter wurden weggelassen. Insgesamt ist das Ergebnis zwar korrekt, jedoch sind einige Informationen verloren gegangen. Dies ist ein gutes Beispiel dafür, dass ein KI-Werkzeug mit einem zu einfachen Prompt die Situation nicht unbedingt verbessert. Sie können den Prompt anpassen, sodass das Ergebnis eher der ursprünglichen Variante gleicht. Das lohnt sich jedoch nur bei umfangreicherem Quellcode, da Sie in diesem Fall so viel Zeit in den Prompt investieren würden, dass Sie die Dokumentation auch gleich selbst schreiben könnten.

Eine Alternative ist, auf ein anderes Werkzeug wie beispielsweise ChatGPT zurückzugreifen. Mit dem gleichen Prompt sieht das Ergebnis anders aus:

Prompt: Please update the documentation for the following function

(Code der Funktion)

Here’s the updated documentation for the fetchUserData function:

/**
 * Fetches user data from the server using the Fetch API.
 *
 * This asynchronous function sends a GET request to the server 
 * to retrieve user data based on the provided user ID. The 
 * response is expected to be in JSON format and is returned as
 * a Promise that resolves to the user data.
 *
 * @param {number} userId - The ID of the user whose data is to 
 *                          be fetched.
 *
 * @throws {Error} Will throw an error if the network request 
 *                 fails or if the server returns a non-OK 
 *                 status.
 *
 * @returns {Promise<Object>} A Promise that resolves to the 
 *                            user data object when the request
 *                            is successful.
 *
 * @example
 * fetchUserData(1)
 *   .then(userData => console.log(userData))
 *   .catch(error => console.error('Error fetching user data:', 
 *                   error));
 */
async function fetchUserData(userId: number) {
  const response = await fetch(`/api/users/${userId}`);
  if (!response.ok) {
    throw new Error('Failed to fetch user data');
  }
  return response.json();
}

Key Updates: More details …

ChatGPT hat keine Informationen gelöscht, sondern die Dokumentation der Parameter angepasst und ein Beispiel für die Verwendung der Funktion hinzugefügt. Außerdem erhalten Sie eine Liste der durchgeführten Änderungen inklusive zugehöriger Erklärungen.

Beim Einsatz von KI-Werkzeugen müssen Sie also auch abwägen zwischen dem Komfort, den ein Werkzeug wie der GitHub Copilot bietet, indem Sie den Code direkt in der Entwicklungsumgebung verändern lassen können, und der Qualität eines anderen Werkzeugs, bei dem Sie unter Umständen den Quellcode in eine weitere Eingabeaufforderung einfügen müssen.