Sourcecode Format

Jeder einzelne Programmierer entwickelt in seinem Leben einen persönlichen Stil Programme zu schreiben. Dabei lässt er sich von Vorlieben, Einsichten und Bequemlichkeiten leiten.

Leider ist es aber so, das man das nur bei Entwicklern tolerieren kann, die für sich selbst arbeiten und deren Sourcecode kaum jemand anders zu sehen bekommt. Bei allen anderen müssen, entgegen der persönlichen Vorlieben, andere Kriterien im Vordergrund stehen.

Dazu gehört als Forderung, das der Sourcecode lesbar sein muss. Ich verstehe darunter, das ich jemandem, der diese Programmiersprache und das Projekt nicht kennt, das Listing eines Modul geben kann und er aus der Struktur und den Kommentaren darin erkennen kann, was grob in dem Modul vor sich geht.

Manche werden hier (zurecht) den Kopf schütteln und behaupten, das das nicht geht. Das ist klar und darum geht es im Kern auch nicht. Kernaussage ist, das ich bereits im Sourcecode dafür sorgen muss das sich jeder, der sich dort einarbeiten muss, einfach zurecht findet. Einarbeitszeiten von mehreren Wochen um einen zusätzlichen Dialog einzubauen oder ein Feld in einem bestehenden zu ergänzen sind untragbar. Vor allem wenn die wichtigen Kernaussagen innerhalb der Entwicklung nur mündlich tradiert werden ist generell etwas schief gelaufen.

Diejenigen die jetzt nicken, sollten sich ihren eigenen Sourcecode oder den der Mitarbeiter in ihrem Projekt einmal genauer anschauen. Wenn man nicht gerade in einer paradiesischen Umgebung arbeitet sehen viele Sourcen nach "Kamikaze"-Programmieren aus. Wenn Code-Reviews nur alle Jubeljahre stattfinden und der Mitarbeiter weiss, das er dann längst in einem anderen Projekt in einer anderen Firma steckt, dann wird zumeist handwerklich sehr schlechte Arbeit geliefert.

Bezahlt wird die Zeche dann vom Kunden bzw. von dem Mitarbeiter, der den Staffelstab in die Hand gedrückt bekommt und dann, zur Verwunderung der Projektleitung, die ersten Monate überhaupt nicht vorwärtskommt.

Ich habe daher für meinen Teil einen einfachen Satz von Regeln aufgestellt, mit dem ich gut zurecht komme. Man mag sich hier heraus picken, was einem passt oder sie so anpassen, das sie dem persönlichen Stil nahe kommen.

Welche Regeln man auch immer auswählt, es ist darauf zu achten, das sie von jedem überall und jederzeit eingehalten werden. Das magische Geheimnis zu verständlichem Sourcecode sind nämlich nicht die Regeln selbst, sondern deren konsequente Anwendung. Wird da nachgelassen oder Ausnahmen gemacht, ist das Regelwerk als Ganzes wertlos.

Jeder Drucker beherrscht 132 Zeichen pro Zeile. Daher ist nicht einzusehen, warum man Source-Code und Kommentare in 80 Zeichen quetschen soll. Jenach Sprache lege ich meist willkürlich eine Spalte fest auf der die Kommentare beginnen und halte diese, soweit möglich, im gesamten Quelltext durch.

Damit das Schreiben einfacher wird sehe ich zu, das der Editor, den ich benutze, das automatische Ausrichten bzw. das Einfügen von Kommentaren an dieser Spalte beherrscht. Oder das man zumindestens ein Tastaturmakro dafür schreiben kann. Ich verwende dafür den EMACS, der jenach Programmiersprache einfach über "ESC ;" Kommentare an eine vorher definierte Spalte verschiebt oder dort neu anlegt. Aber auch in Visual C++ oder anderen Entwicklungsumgebungen lässt sich ähnliches einrichten.

Viele schwärmen von standardisierten Kommentarblöcken zwischen den Funktionen die nochmal den Name der Funktionen, der Parameter, ihre Typen und Funktionen und ähnliches enthalten. Ich frage mich ob einer davon sich jemals den selben Sourcecode nach 3 oder 4 Wartungszyklen angeschaut hat. Bis dahin hat sich ggf. alles geändert, vom Funktionsnamen über die Parametertypen und deren Namen und die Verwendung. Und hat sich jemand die Mühe gemacht die Kommentare anzupassen? Natürlich nicht ... Warum auch...

Ähnliches passiert dokumentierten Algorithmen. Wird daran gebastelt, diese geändert, sollten die Kommentare angepasst werden. Aber in der Realität geschieht das äusserst selten. Was macht man bei so einer Zeile im Sourcecode?

i += -1; // i erhöhen

Hier also die erste Regel:

Niemals etwas dokumentieren, das ich auch im Code schreiben kann.

Aber wie kann das eine Regel sein? Habe ich nicht vorher gesagt jemand, der diese Programmiersprache und das Projekt nicht kennt, das Listing eines Modul geben will? Nun, das obige Code-Schnipsel ist ein gutes Beispiel daür, wie man es nicht machen sollte. Der überflüssige Kommentar kommentiert was getan wird, aber nicht warum.

In diesem Beispiel ist dokumentiert worden, das man gerne i erhöhen möchte, aber warum das zu geschehen hat ist nicht beschrieben. Was man tut sollte aber nur in den wenigsten Fällen dokumentiert werden. Und jeder was-Kommentar ist in sich eigentlich schon ein Hinweis darauf, das der Entwickler selber seine eigenen Absichten im Code selbst nicht sichtbar genug darstellt. In diesen Fällen sind das Hinweise auf potentielle Probleme bei der Wartung später und diese sollten darum im Code-Review sofort ausgeräumt werdem.

Die einzige erlaubte Ausnahme ist der Aufruf externer Funktionen. Funktionen deren Namen und Aufgabe so verschleiert ist, das sie über normalen Code nicht abbildbar ist.

Hier also die zweite Regel:

Niemals das dokumentieren was getan wird, sondern dokumentieren warum man etwas tut.

In dem Beispiel-Schnipsel haben wir also zwei unabhängige Teile mit verschiedenen Aufgaben. Nehmen wir mal an, das der Kommentar wirklich dokumentieren würde warum der Wert erhöht werden soll. Dann müsste der Code ja dokumentieren, was getan wird. Tut er das denn?

Die Verwendung von geeigneten Variablennamen ist eine Wissenschaft für sich. Beginnen wir mit der Gültigkeit eines Namens. Nicht in jeder Programmiersprache hat der Programmierer Einfluss darauf wie lange eine Variable gültig ist. In Pascal definiere ich die Variablen im Kopf der Funktion/Procedure und sie sind von da ab bis zum Ende gültig.