✳ IskraAI

Dokumentation aus Code: Wie man ein genaues Prompt erstellt

Das Tool "Code-Dokumentationsautor" erstellt Textbeschreibungen übergebenener Funktionen: Parameter, Rückgabewerte, Beispiele und Einschränkungen. Das Ergebnis hängt davon ab, wie genau das Prompt formuliert ist. In diesem Artikel werden wir besprechen, was in die Eingabefelder geschrieben wird, wie man gelungene Prompts von schlechten unterscheidet, wie man den fertigen Text überprüft und welche Einschränkungen zu beachten sind. Alle Code-Beispiele und Prompts in diesem Artikel sind Lehrillustrationen, keine Ergebnisse echter Ausführungen.

Tool öffnen: Code-Dokumentationsautor ↗

Was das Tool macht und warum die Formulierung wichtig ist

"Code-Dokumentationsautor" ist ein Web-Formular mit Textfeldern. Sie fügen einen Code-Ausschnitt ein, fügen bei Bedarf Erklärungen hinzu, wählen die Ausgabe Sprache und drücken die Generieren-Taste. Das fertige Ergebnis erscheint in einem separaten Panel: Es kann kopiert oder als einfache Textdatei TXT heruntergeladen werden. Das Tool führt keinen Code aus und überprüft ihn nicht auf Fehler -- es erstellt nur eine Beschreibung basierend auf dem Text, den Sie übergeben.

Die Qualität der Beschreibung hängt direkt von den Eingabedaten ab. Wenn Sie nur die Funktionssignatur ohne Erklärungen einfügen, kann das Tool die Bestimmung der Parameter falsch vornehmen, unnötige Details erfinden oder wichtige Einschränkungen übersehen. Je spezifischer Sie beschreiben, was die Funktion macht und was genau in der Dokumentation widergespiegelt werden soll, desto näher wird das Ergebnis Ihrer Erwartung entsprechen.

Es ist zu bedenken, dass das Tool nur mit Text arbeitet. Es lädt keine Dateien hoch, verbindet sich nicht mit Repositories und speichert keine Anfrage-Historie. Alles, was in die Dokumentation soll, muss in den Eingaben beschrieben werden.

Lehrillustration. Eingabe: def add(a, b): return a + b. Erklärung: "Beschreiben Sie Parameter als Zahlen, Rückgabe -- Summe, fügen Sie Beispiel aufruf hinzu". Solche Eingabe liefert vorhersehbarere Ergebnisse als eine einzelne Code-Zeile ohne Erklärungen.

Eingabefelder und ihre Zweckbestimmung

Das Formular enthält zwei Felder. Erstes -- "Code und Fehlermeldung" -- ist bestimmt für den eigentlichen Code-Ausschnitt und kurze Erklärungen dazu. Maximale Länge dieses Feldes -- 8000 Zeichen. Zweites Feld -- "Plattform oder Anwendung" -- legt den Kontext fest: Programmiersprache, Version, Einsatzumgebung. Seine Länge ist auf 1000 Zeichen beschränkt.

Im Code-Feld ist es nützlich, einen oder zwei Sätze über die Zweckbestimmung der Funktion hinzuzufügen: welche Datentypen erwartet werden, was bei einem Fehler zurückgegeben wird, gibt es besondere Fälle. Das ist keine obligatorische Anforderung, aber solche Details helfen dem Tool, die Beschreibung präziser zu formulieren und nicht erfundenes Verhalten zu dichten.

Feld "Plattform oder Anwendung" beeinflusst den Stil der Beispiele und die Terminologie. Wenn Sie Python 3.9 und ein Beispiel für Anfänger angeben, wird die Beschreibung einfacher sein, als wenn Sie beispielsweise einen industriellen Web-Service auf JavaScript angeben. Der Kontext hilft dem Tool, passende Formulierungen auszuwählen.

Lehrillustration. Feld "Code": def add(a, b): return a + b. Feld "Plattform": Python 3.9, Beispiel für Anfänger.

Wie man ein gelungenes Prompt erstellt

Ein gutes Prompt umfasst in der Regel vier Elemente. Kontext -- wo und wie die Funktion verwendet wird. Ziel -- was genau dokumentiert werden soll: Parameter, Rückgabewert, Beispiel, Einschränkungen. Format -- in welcher Form das Ergebnis präsentiert werden soll; das Tool gibt nur normalen Text aus, daher sollte man im Voraus entscheiden, ob eine Liste oder ein zusammenhängender Absatz benötigt wird. Einschränkungen -- was nicht erwähnt werden soll oder welche Details zwingend erforderlich sind.

Zum Beispiel, wenn eine Funktion nur für die interne Verwendung bestimmt ist, geben Sie das an, damit in der Beschreibung keine Beispiele für externe Benutzer auftauchen. Wenn die Funktion Ausnahmen werfen kann, bitten Sie darum, den Zustand zu beschreiben, unter dem dies geschieht.

Je spezifischer das Prompt, desto unwahrscheinlicher ist es, dass das Tool unnötiges hinzufügt oder Wichtiges übersieht. Allgemeine Phrasen wie "mache gut" tragen keinen Sinn und helfen nicht. Es lohnt sich, einige Sekunden für die Verfeinerung zu verwenden, anstatt später das Ergebnis umzuschreiben.

Lehrillustration. Kontext: Die Funktion add wird in einem Unterrichts-Rechner verwendet. Ziel: Parameter a und b beschreiben, Rückgabewert, Beispiel-Aufruf. Format: normaler Text. Einschränkung: andere Funktionen nicht erwähnen.

Vergleich von schlechtem und gutem Prompt

Betrachten wir eine Lehr-Beispiel-Funktion in Python: def add(a, b): return a + b. Schlechtes Prompt -- einfach "Dokumentieren Sie es". In der Antwort kann das Tool eine allgemeine Beschreibung ohne Angabe von Typen und ohne Beispiel geben. Gutes Prompt enthält Präzisierungen: "Beschreiben Sie die Funktion add: Parameter a und b -- Zahlen, gibt Summe zurück. Fügen Sie Beispiel add(2, 3) -> 5 hinzu. Kennzeichnen, dass bei Übermittlung von Zeichenfolgen deren Verkettung erfolgt. Plattform: Python 3.9".

Im guten Fall wird explizit gesagt, dass die Parameter Zahlen sind, aber ebenfalls eine Besonderheit bei Zeichenfolgen vermerkt. Das hilft dem Tool, eine vollständigeren Beschreibung zu erstellen. Erwähnen Sie die Zeichenfolgen nicht, kann die Dokumentation unvollständig sein.

Auch die Angabe der Plattform ist wichtig: ohne ihr können Beispiele nicht dem Python-Syntax entsprechen. Der Kontext legt den erwarteten Stil und die Terminologie fest, daher sollte er auch bei kurzen Prompts angegeben werden.

Lehrillustration. Gutes Prompt: "Dokumentieren Sie die Funktion add(a, b) auf Python. Beschreiben Sie Parameter als Zahlen, Rückgabe -- Summe. Fügen Sie Beispiel add(2, 3) = 5 hinzu. Kennzeichnen, dass bei Übermittlung von Zeichenfolgen Konkatetation erfolgt. Einschränkung: maximal 100 Wörter".

Ergebnis überprüfen

Nach der Generierung erscheint der Text in einem separaten Panel. Er kann kopiert oder im TXT-Format heruntergeladen werden. Prüfen Sie, ob alle Parameter beschrieben sind, ob das Rückgabewert zum Code passt, ob das Beispiel korrekt ist. Wenn das Tool einen Fehler gemacht hat, verfeinern Sie das Prompt und generieren Sie erneut.

Das Tool führt keinen Code aus, daher können Beispiele syntaktisch korrekt sein, aber auf echten Daten nicht geprüft. Bei komplexen Funktionen sollten Beispiele manuell getestet werden. Das ist besonders wichtig, wenn die Dokumentation für andere Entwickler bestimmt ist.

Das Modell kann Fehler machen, und die Warteschlange und Verfügbarkeit des Services können sich ändern. Überprüfen Sie immer den generierten Text vor der Verwendung. Wenn das Ergebnis nicht zufriedenstellend ist, ändern Sie die Formulierung des Prompts und fügen Sie fehlende Details hinzu.

Lehrillustration. Prüfung: In der Beschreibung sollte angegeben sein, dass add die Summe von a und b zurückgibt. Wenn geschrieben steht "gibt Differenz zurück", bedeutet das, dass das Tool einen Fehler gemacht hat -- verfeinern Sie das Prompt.

Einschränkungen und typische Fehler

Das Tool lädt keine Dokumente hoch, führt keine Batch-Verarbeitung durch, speichert keine Historie und integriert sich nicht in andere Services. Es erstellt keine Bilder, Audio oder Video. Die Eingabe ist beschränkt: 8000 Zeichen für Code und 1000 für Plattform. Das Ergebnis -- nur normaler Text. Export ist in TXT möglich; Formate DOCX und PDF werden nicht unterstützt.

Typischer Fehler -- zu kurzes Prompt ohne Angabe von Sprache und Ziel. Ein anderer Fehler -- Überladung mit unwichtigen Details, die nicht mit der Funktion zusammenhängen. Dritter -- Erwartung, dass das Tool den Kontext selbst versteht, wenn er nicht beschrieben wird.

Es sollte nicht veranlasst werden, das Tool etwas zu tun, das es nicht kann: zum Beispiel ein DOCX oder PDF generieren. Wenn ein anderes Format benötigt wird, muss der Text manuell konvertiert werden. Auch sollte nicht darauf gerechnet werden, dass das Tool Batch-Verarbeitung leistet: Es arbeitet mit einem Code-Ausschnitt nach dem anderen.

Lehrillustration. Fehler: "Dokumentieren Sie alle Funktionen in einem Projekt". Das Tool verarbeitet einen Ausschnitt nach dem anderen. Bessere Aufteilung der Aufgabe in mehrere Anfragen.

Ein genaues Prompt ist die Grundlage für qualitativ hochwertige Dokumentation. Kontext, Ziel, Format und Einschränkungen angeben, Beispiele bringen, Ergebnis prüfen und bei Bedarf die Eingabe nachjustieren. Behaltet die Einschränkungen im Gedächtnis: Das Tool führt keinen Code aus, speichert keine Daten und unterstützt keine komplexen Formate. Bei sorgfältiger Anwendung hilft "Code-Dokumentationsautor", Funktionen schneller zu beschreiben und die Dokumentation aktuell zu halten.

Tool öffnen: Code-Dokumentationsautor ↗

Oberflächenübersetzungen sind maschinell unterstützt und können eine Überarbeitung benötigen.