Veröffentlicht am

Zeit sparen beim Dokumentieren: einfacher Trick

Zeit sparen bei Dokumentieren

Zeit sparen beim Dokumentieren: einfacher Trick

Nur dokumentierter Code ist guter Code. Das hören wir immer wieder und wissen es aus Erfahrung.

Doch endlich läuft der Code und wir haben noch sooo viel zu tun – also nehmen wir uns ganz fest vor: morgen wird dokumentiert. 

Mit einem einfachen Trick dokumentiert der Code sich selbst.

Sprechende Bezeichner!

Genau: “Bezeichner” und nicht “Bezeichnung”.

Bezeichner sind die Namen für Variablen, für Funktionen, Methoden, Klassen, Objekte, etc.

Ein kurzer Test:

Welcher (Python) Code ist besser verständlich

x = 1

oder 

anzahl_autos = 1

Autorin: Ursula Deriu

Bezeichner für den Computer

Für den Computer ist es einerlei: sowohl x als auch anzahl_autos, beides sind Bezeichner (englisch: identifier).

Der jeweilige Compiler – oder im Fall von Python der Python-Interpreter – löst den Bezeichner auf in eine interne Adresse und sorgt dafür, dass jedes Vorkommen des Bezeichners jeweils mit derselben internen Adresse aufgelöst wird.

Diese interne Adresse verweist auf eine Stelle im Memory – genauer im RAM (Random Access Memory) und an dieser Stelle wird das Programm den aktuellen Wert finden, mit dem es rechnen soll.

In diesem Beispiel bezeichnen x und anzahl_autos zwei Variablen. Der Grund ist ein einfacher, der Wert, der Variable kann ändern. In unserem Beispiel oben, ist er jeweils 1 also ein konstanter Wert.

Mit dem Wert der Variablen können wir rechnen – Beispiel:

x = x * 2

anzahl_autos = anzahl_autos * 2

Für den Computer bedeuten die beiden Codezeilen das Gleiche:

Der aktuelle Wert der Variablen wird mit Hilfe der internen Adresse aus dem RAM geholt und in eines der Register in der CPU geschrieben. Danach wird der Wert mit 2 multipliziert und das Ergebnis wird aus dem Register wieder an die mit der internen Adresse bezeichneten Stelle im RAM geschrieben.

Sprechende Bezeichner

Für den Menschen ist der Unterschied jedoch erheblich:

anzahl_autos = anzahlAutos * 2;

anzahl_kalorien = anzahl_kalorien * 2

gehalt = gehalt * 2

Blitzschnell leuchtet in unserem Gehirn jeweils ein völlig anderes Bild auf. Der nackte Code erhält Kontext und das Programm wird besser verständlich.

Es lohnt sich, beim Programmieren die Bezeichner mit Bedacht zu wählen. Das Programm und dessen Absicht werden gleich viel besser verständlich.

Sprechende Bezeichner dokumentieren Funktionen und Methoden

Dasselbe gilt für die Bezeichner von Funktionen und Methoden.

def y(x):
    return (x * 2)

def verdopple_das_verkehrsaufkommen(anzahl_autos):
    return(anzahl_autos * 2)

Die Funktion y und die Funktion verdopple_das_verkehrsaufkommen sind für den Computer absolut identisch.

Nicht jedoch für den menschlichen Leser.
y als Bezeichner für die Funktion gibt uns keinen Kontext. Um sie zu verstehen, müssen wir den Code genau lesen. Zugegeben: in diesem Beispiel ist das trivial.
Doch das ist die Ausnahme – Funktionen können weitere Funktionen aufrufen, sogar sich selbst. Funktionen können beliebig komplex sein.

Wir könnten bei der Funktion y einen Kommentar einfügen, um die Absicht der Funktion zu erklären – das ist sowieso eine gute Idee, bedeutet aber, dass wir neben dem Programmcode immer auch die Kommentare pflegen müssen.

Und wir müssen uns bei der Analyse des Codes genau erinnern, was y und was x bedeutet.

Es geht auch einfacher: Wir wählen sprechende Bezeichner – so wie bei der Funktion verdopple_das_verkehrsaufkommen und das Programm dokumentiert sich selbst.

Deprecated Code oder: Bezeichner pflegen

Die Medaille hat auch eine Kehrseite: Sprechende Bezeichner erzeugen beim menschlichen Leser einen Kontext und sie können damit in die Irre führen.

def verdopple_das_verkehrsaufkommen(anzahl_autos):
    return(anzahl_autos * 3)

Hier verspricht die Bezeichnung ein Verdoppeln – der Code jedoch verdreifacht den Wert der übergebenen Variablen.

Das bedeutet also, dass wir entweder den Bezeichner der Funktion überall anpassen oder aber, eine neue Funktion schreiben.

Bezeichner anpassen

Anpassen der Bezeichnung ist wiederum ein zweischneidiges Schwert – ist das Programm nicht brandneu, dann wissen wir nicht, ob die Funktion nicht schon von weiteren Programmen verwendet wurde.

Wir müssen also vorsichtig sein, uns schreiben besser eine neue Funktion mit einer neuen sprechenden Bezeichnung.

Deprecated

Die alte Funktion können wir als deprecated bezeichnen, und so den Programmierern, die sie vielleicht schon verwendet haben, anzeigen, dass wir sie in Zukunft löschen werden.

Der Computer hält uns nicht davon ab, beliebigen Unsinn zu treiben. Folgendes ist formal gültiger Code:

anzahl_kalorien = 95
kalorien_die_du_essen_darfst = verdopple_das_verkehrsaufkommen(anzahl_kalorien)

Der Computer wird die Berechnung emotionslos ausführen und an der Speicherstelle kalorien_die_du_essen_darfst die Zahl 190 speichern und damit weiterrechnen.

Ob wir als Programmierer den Code noch verstehen, ist jedoch sehr zu bezweifeln. Es lohnt sich, eine neue Funktion mit passendem Bezeichner zu schreiben und so den inhaltlichen Kontext “Verkehrsaufkommen” vom Kontext “Kalorienbedarf” zu trennen.

[/vc_row_inner]

Fazit:

  • Sprechende Bezeichner schaffen Kontext für den Menschen. Der Code dokumentiert sich selbst.
  • Sie ergänzen die Kommentare und kürzen die Kommentare ab.
  • Die Bezeichner sind mit Bedacht zu wählen und müssen der Funktionalität entsprechen.
  • Deprecated sagt aus, dass eine Funktion in Zukunft nicht mehr verfügbar sein wird.
  • Klick aufs Bild und hol dir das kostenlose Cheat Sheet Wichtigste Python-Datentypen