Wissenswerte

Wissenswerte

Lesbarer Code ist besser als Dokumentation.

Ein gutes Buch zu lesen macht Spaß, ein schlechtes legen wir schnell zur Seite. Auch das Lesen von Code sollte daher Spaß machen. Darum halte ich gerne ein Plädoyer für sauberen Code. Kommentare im Code sind immer dort notwendig, wo der offensichtlich einfache Weg bei der Umsetzung nicht eingeschlagen wurde. Das kann ein Workaround für einen Bug in einem Framework sein. Oder es ist eine Optimierung des Codes. Alle diese Fälle zeichnen sich dadurch aus, dass wir am Code den Grund für die unerwartete Umsetzung nicht erkennen können.

Aber lesbarer Code kann keine Dokumentation ersetzen. Fachliche Zusammenhänge, Grundlagen von Algorithmen oder ganz allgemein Hinweise zur Motivation einer bestimmten Umsetzung fehlen im Code. Hier muss es unser klares Ziel sein, dieses wertvolle Wissen im Wiki zu sichern. Die einfache Regel ist: Was nicht im Code “gelesen” werden kann (“Wie”), gehört ins Wiki (“Wer”, “Wann” und “Warum”).

Gibt es eine Dokumentation, dann muss es das Ziel der Entwickler sein, die skizzierten Lösungen umzusetzen. Sollte sich bei der Umsetzung eine bessere Lösung ergeben, wird nicht die Abweichung von der Dokumentation im Code durch Kommentare erklärt, sondern die Dokumentation wird geändert und beschreibt die neue Lösung. Dieses Vorgehen gilt auch für den Fall, dass eine Lösung erst erarbeitet werden muss. Das Ergebnis ist am Ende lesbarer Code und eine dazu passende Dokumentation.