Übersichtliche Quelltexte unabhängig von der Programmiersprache

Als langjähriger Entwickler schlägt man sich bei einem Blick auf den eigenen Quellcode von früheren Zeiten doch sehr oft die Hände über dem Kopf zusammen “Wer soll das bitte lesen? Wo sind alle die Kommentare abgeblieben? Für was steht gleich die Variable $a2?”. Gerade heute habe ich wieder über fremden Quellcode schauen müssen und dachte mir, dass dies ein guter Anlass für ein solches Posting wäre.

Worauf kommt es bei einem guten Quelltext an?

Nun zunächst einmal sollte das Dokument möglichst nicht mehrere 1000 Zeilen groß sein. Quelltexte dieser Größe lassen sich nur schwer überblicken. Mehrere kleine Dokumente lassen sich. Nach meiner Erfahrung in Hinsicht auf Teamarbeit und Dokumentation hat es sich oft gezeigt, dass sich das Aufdröseln unterm Strich gelohnt hat. Allerdings trifft das nicht immer zu!

Sinnvolle Benennung von Variablen

Weiterhin sollte ein Programmierer sich bei der Benennung von Variablen lieber 10 Minuten zeit nehmen, anstatt die Programmierung mit Sinn entleerten Variablen Bezeichnungen fort zu setzen. Nehmen wir zum Beispiel an, eine Variable für die Gesamtsumme eines Warenkorbes deklariert werden muss.

  1. $b = 999999.99;

Ok b wie Basket klingt ok oder? Nein das geht absolut gar nicht! Denken Sie sich mal in die Situation hinein, Sie müssten Ihren Quelltext in 2 oder 3 Jahren überarbeiten. Prost Mahlzeit! $b ist einfach nur Sinn entleert.

Nehmen wir uns doch etwas mehr Zeit bei der Findung des Variablennamens:
Welchen Wert enthält die Variable? Die Gesamtsumme aller Waren im Warenkorbes…
Inklusive oder exklusive Mehrwertsteuer? inklusive Mehrwertsteuer…

Demzufolge ist es doch ein Einfaches die Variable schlüssig zu benennen oder?

  1. $basketSumBrutto = 999999.99;

Den Sinn dieser Variable hat man immer sofort vor Augen stimmts? Die einzige  Art von Variablen, die möglichst kurz benannt werden sollten, sind Zählvariablen.

Einrückung Einrückung und nochmal Einrückung

In vielen Programmiersprachen hat es sich durchgesetzt, mittels Tabulator einzurücken. Das hat den Vorteil, dass ein TAB vom Programmierer in der Regel in seiner Entwicklungsumgebung frei konfigurierbar ist. So kann ein TAB bei einem Programmierer, welche auf Quetschkommode steht, 2 Leerzeichen entsprechen und bei den meisten anderen wird der TAB genau 4 Leerzeichen entsprechen. Es ist jedoch zu beachten, dass der Editor die Entwicklungsumgebung die Tabs beim Speichern nicht in Leerzeichen konvertiert. Denn das wäre dann fatal! Einige Unix Programmierer werden mich jetzt schlagen, aber ich lege mich nachfolgend auf die Einrückung mittels TAB fest.

Betrachten wir uns folgendes Snippet:

  1. $sprache="deutsch";
  2. $vorname="Max";
  3. $nachname="Mustermann";
  4. $strasse="Musterstraße";
  5. $hausnr="10";
  6. $plz="01234";
  7. $ort="Musterstadt";

Auf den ersten Blick sieht das fast ok aus, aber das geht viel besser und übersichtlicher:

  1. $sprache = "deutsch";
  2. $vorname = "Max";
  3. $nachname = "Mustermann";
  4. $strasse = "Musterstraße";
  5. $hausnr = "10";
  6. $plz = "01234";
  7. $ort = "Musterstadt";

Und was liest sich jetzt besser? Klar macht es etwas Arbeit, den Code wie eben gezeigt etwas schöner zu gestalten, aber eins ist sicher: Nachfolgend über den Code blickende Dritte haben sehr viel mehr Vergnügen beim Lesen. Und auch der Autor des Quelltextes wird selbst nach Jahren noch sagen – super übersichtlich! Für Entwickler, die innerhalb eines größeren Teams arbeiten, sollte dieser Stil zu guten Pflicht gehören.

Kommentare

Mit dem Kommentaren haben es die wenigsten Programmierer. Die meisten setzen der Einfachheit gar keine Kommentare. Autsch! Viele Programmierer, die dann doch Kommentare setzen, meinen es mit dem Kommentieren aber leider zu gut. Zum Beispiel sind solche Kommentare hier völliger Blödsinn und können getrost weg gelassen werden.

  1. // Sprache des Clienten
  2. $sprache  = "deutsch";
  3. // Vorname des Clienten
  4. $vorname  = "Max";
  5. // Nachname des Clienten
  6. $nachname = "Mustermann";
  7. // Straße des Clienten
  8. $strasse  = "Musterstraße";
  9. // Hausnummer des Clienten
  10. $hausnr      = "10";
  11. // Postleitzahl des Clienten
  12. $plz      = "01234";
  13. // Ort des Clienten
  14. $ort      = "Musterstadt";

Hallo? Davon ausgehend, dass wir inzwischen Variablen sinnvoll benennen, sind diese Kommentare doch wirklich absolut überflüssig. Zumal diese Kommentare den gesamten Variablenblock zerstören. Wenn man hier schon unbedingt kommentieren möchte, dann empfehle ich maximal einen Kommentar oberhalb dieses thematisch zusammen gehörigen Blockes. Wie gesagt wenn überhaupt!

  1. // Clientendaten für Musterdatensatz
  2. $sprache = "deutsch";
  3. $vorname = "Max";
  4. $nachname = "Mustermann";
  5. $strasse = "Musterstraße";
  6. $hausnr = "10";
  7. $plz = "01234";
  8. $ort = "Musterstadt";

Doch wo machen Kommentare eigentlich Sinn?

Ganz einfach. Kommentare sollten Codestrukturen beschreiben, die nicht selbsterklärend sind. Das können zum Beispiel Funktionen, Klassen oder größere Codeblöcke sein. Hier bietet es sich jedoch an, die Kommentare zu konsolidieren beziehungsweise zu bündeln (der Code und der Kommentar sind examplarisch zu sehen).

  1. // Berechnung der Gesamtsumme aller Waren innerhalb des Warenkorbs
  2. // Die Beträge in Array $basketItems liegen netto vor! Das Array
  3. // $basketItems enhält folgende Struktur:
  4. // [][item] =>
  5. // [
  6. // [id] => int,
  7. // [menge] => int,
  8. // [preis] => double
  9. // ]
  10. $basketSumNetto  = 0;
  11. $basketSumBrutto = 0;
  12. foreach ($basketItems as $key => $item_x)
  13. {
  14. $basketSumNetto += $item_x ['menge'] * $item_x ['preis'];
  15. }
  16. $basketSumBrutto = $basketSumNetto * 1.19;

Bei Klassen beziehungsweise Methoden bietet es sich an auf standardisierte Techniken zur Dokumentation zurück zu greifen.

Es gibt quasi für nahezu jede Programmiersprache ein passendes Pendant. Der Vorteil dieser Tools ist neben der Standardisierung die entstehende Quelltext Dokumentation in Form einer übersichtlichen Ansammlung von sämtlichen dokumentierten Quellcode. Beispiel für PHPDoc

Was wir gelernt haben

Es ist nicht entscheidend, eine Quellcode möglichst schnell zu programmieren, sondern möglichst gut lesbar, dokumentiert, durchdacht und fehlerfrei. Die Zeit, die man zur Optimierung des Quelltextes verwendet, spart man sich später beim Debugging oder bei anstehenden Erweiterungen am Quelltext. Man sollte sich als Programmierer einen programmierten Quellcode nach etwas längerer Zeit mit etwas Abstand nochmals ansehen und nach dokumentieren. Das Problem ist nämlich eine Betriebsblindheit. Seinen eigenen Quellcode kennt man zum Zeitpunkt des Schreibens immer. Daher erscheinen viele Dinge logisch, sind es jedoch ganz und gar nicht.

Ich habe mir all diese kleinen Dinge in einem tollen Team angelernt. Natürlich sollten beim gemeinsamen Arbeiten innerhalb eines Teams viele weitere kleine Details schriftlich fixiert und als Style Guide oder wie auch immer man dieses Dokument bezeichnen mag zur Verfügung gestellt werden. Ansatzpunkte könnten hier sein:

  • Variablen Buckelschreibweise oder Unterstrichschreibweise
  • Festlegung der zu verwendenden Kommentarsyntax (z.B. PHPDoc)
  • Codestruktur (z.B. oben Logik unten Ausgabe)
  • Instanzen von Objekten mit großen ANfangsbuchstaben

Ein Brainstorming innerhalb eines lockeren Teammeetings wird noch viele weitere Punkte auf die Liste bringen.

Be Sociable, Share!

Keine Kommentare

Noch keine Kommentare

RSS-Feed für Kommentare zu diesem Beitrag. TrackBack URI

Hinterlasse einen Kommentar