Wie dokumentieren Sie den Zweck, den Umfang und die Ziele Ihrer Algorithmen?

1 Warum Algorithmen dokumentieren?

Das Dokumentieren von Algorithmen ist nicht nur eine gute Angewohnheit, sondern in vielen Zusammenhängen auch eine professionelle Anforderung. Es hilft Ihnen und anderen, die Begründung, Funktionalität und Grenzen Ihrer Algorithmen zu verstehen. Es erleichtert auch die Kommunikation, Zusammenarbeit und Überprüfung zwischen verschiedenen Beteiligten, wie Entwicklern, Testern, Prüfern, Kunden und Benutzern. Darüber hinaus kann die Dokumentation von Algorithmen die Qualität, Wartbarkeit und Skalierbarkeit Ihres Codes verbessern sowie Fehler, Bugs und Mehrdeutigkeiten verhindern.

2 Was soll dokumentiert werden?

Die wichtigsten Elemente, die Sie für Ihre Algorithmen dokumentieren sollten, sind der Zweck, der Umfang und die Ziele. Der Zweck beschreibt, was der Algorithmus tut und warum er benötigt wird. Der Bereich definiert die Eingaben, Ausgaben, Parameter und Annahmen des Algorithmus. Die Ziele spezifizieren die erwarteten Ergebnisse, die Leistung und die Einschränkungen des Algorithmus. Abhängig von der Komplexität und dem Kontext Ihrer Algorithmen können Sie auch andere Aspekte dokumentieren, z. B. das Algorithmusdesign, Pseudocode, Flussdiagramme, Testfälle und Referenzen.

3 Wie dokumentiert man?

Wenn Sie Ihre Algorithmen dokumentieren, sollten Sie eine klare, prägnante und konsistente Sprache und Terminologie verwenden. Kommentare, Anmerkungen oder Docstrings in Ihrem Code können helfen, die Logik und Details Ihrer Algorithmen zu erklären. Darüber hinaus können externe Dokumentationstools wie Markdown, LaTeX oder HTML strukturiertere und lesbarere Dokumente erstellen. Verwenden Sie zum Organisieren und Veranschaulichen Ihrer Dokumentation Überschriften, Abschnitte, Listen, Tabellen, Diagramme und Codeausschnitte. Verwenden Sie außerdem konsistente und aussagekräftige Namenskonventionen für Variablen, Funktionen, Klassen und Dateien. Denken Sie schließlich daran, Ihre Dokumentation zu aktualisieren, wenn Sie Ihre Algorithmen ändern.

4 Beispiel für eine Dokumentation

Um zu veranschaulichen, wie Sie den Zweck, den Umfang und die Ziele Ihrer Algorithmen dokumentieren können, sehen wir uns ein einfaches Beispiel für einen Algorithmus an, der die Fakultät einer positiven ganzen Zahl berechnet. Die Fakultät einer Zahl n ist das Produkt aller positiven ganzen Zahlen von 1 bis n. Die Fakultät von 5 ist z. B. 5 x 4 x 3 x 2 x 1 = 120. Hier sehen Sie, wie wir diesen Algorithmus mit Python-Docstrings dokumentieren können:

def fakultät(n):

"""Berechnen Sie die Fakultät einer positiven ganzen Zahl.

Zweck: Der Algorithmus berechnet die Fakultät einer gegebenen Zahl mit Hilfe einer rekursiven Funktion.

Gültigkeitsbereich: Der Algorithmus nimmt eine positive ganze Zahl n als Eingabe und gibt eine positive ganze Zahl als Ausgabe zurück. Es wird davon ausgegangen, dass n gültig ist, und es wird nicht nach Fehlern oder Ausnahmen gesucht.

Ziele: Der Algorithmus zielt darauf ab, den korrekten faktoriellen Wert für jede positive ganze Zahl n in kürzester Zeit und mit möglichst wenig Speicher zurückzugeben.

Argumente:

n (Int): Die positive ganze Zahl, deren Fakultät berechnet werden soll.

Ertrag:

int: Die Fakultät von n.

Beispiele:

>>> Fakultät(5)

120

>>> Fakultät(0)

1

"""

Wenn n == 0 oder n == 1:

Rückgabe 1

oder:

return n * Fakultät(N-1)

5 Hier ist, was Sie sonst noch beachten sollten

Dies ist ein Ort, an dem Sie Beispiele, Geschichten oder Erkenntnisse teilen können, die in keinen der vorherigen Abschnitte passen. Was möchten Sie noch hinzufügen?