Ich werde leider immer wieder mit unschönen Quellcodes konfrontiert. Informatiker beschäftigten sich meistens mehr mit der Programmlogik, als sich Gedanke über das Dokumentieren/Kommentieren zu machen. Ich werde hier das Rad nicht neu erfinden, sondern nur bekannte Sachverhalte an Beispielen aufzeigen. Dabei bin ich auf die folgenden Punkte gekommen:
- Schreibe keine überflüssigen Kommentare!
- Schreibe kompakten Quellcode!
- Teile größere Dateien in kleinere auf, aber vergesse die Ordnungsstruktur nicht.
Kommentare
Beim Kommentieren von Softwareprojekten gibt es zwei extreme Fälle, zu wenige oder zu viele Kommentare. Viele werden sich fragen warum zu viele Kommentare ein Problem darstellen. Man sollte meinen, dass mehr Informationen mehr Hilfe bieten. Dies stimmt in den meisten Fällen nicht.
Beim Lesen des Quellcodes muss das Gehirn alle Informationen verarbeiten. Natürlich sind da zusammengefasste Informationen von einem komplizierten Ablauf hilfreich. Aber überflüssige redundante Informationen müssen ebenfalls vom Gehirn verarbeitet werden. Die Syntax der meisten höheren Programmiersprachen ist selbsterklärend und benötigt keine Kommentare. Ein paar Beispiele:
Beispiel 1 (c++):
int a = 5; // Die Variable a wird mit 5 vorbelegt
Sehr viel schlimmer geht es eigentlich nicht. Das Kommentar beschreibt nur das offensichtliche. Wichtiger wäre allerdings zu sagen wofür die Variable gedacht ist.
int a = 5; // Anzahl der Äpfel
Beispiel 2 (Delphi):
//--------------------------------------------------------------------- // // Typ : Function // CheckValue // Funktion : CheckValue ueberprueft den Wert MyValue // Parameter : Value1: Integer; Value2: Integer // Rueckgabe : Boolean // //--------------------------------------------------------------------- function TForm.CheckValue(Value1: Integer; Value2: Integer): Boolean; begin //... end;
Beschreibungen für Funktionen sind zwar wichtig, aber in den ersten 9 Zeilen steht nichts wissenswertes. Alle Informationen können der Zeile 10 entnommen werden. Dafür fehlt die Information was diese Funktion eigentlich macht und was für Eigenschaften mit den Parametern beschrieben werden.
Der Grund für die überflüssigen Kommentare kommt wahrscheinlich beim Erlernen des Programmierern zustande. Jedem Informatiker wird nahegelegt, sein Quellcode zu Kommentieren. Dafür werden meistens sehr einfache Beispiele verwendet und die Kommentare erklären nur offensichtliche Sachverhalte. Viele Informatiker gewöhnen sich aber diesen Stiel an.
In der Kürze liegt die Würze
Wie bereits erwähnt, muss das Gehirn alle Informationen verarbeiten. Dies geschieht meistens ganz unbewusst. Es werden große komplexe Objekte in kleinere aufgeteilt. Auch beim Lesen dieses Beitrags, denn hier wird der gesamte Text Stück für Stück verarbeitet. Das Gleiche passiert auch beim Lesen vom Quellcode. Darum sollte drauf geachtet werden, möglichst wenig Quellcode zu schreiben. Denn hier ist weniger mehr. Wenn dein Projekt 10.000 Zeilen Code groß ist, hört sich das vielleicht cool an, aber sie helfen nicht einen Fehler zu finden.
Die Kompaktheit des geschriebenen, hängt von dessen Programmiersprache ab. Nach Möglichkeit sollte immer die kürzere Schreibweise gewählt werden. Nicht falsch verstehen, Leerzeichen und Zeilenumbrüche enthalten keine Informationen und können daher beliebig verwendet werden. Einige Beispiele sollen dies verdeutlichen:
Beispiel 1 (c++):
if geheim == true then{
ausgabe = false;
}
else{
ausgabe = true;
}
Zum einen sind die geschleiften Klammern überflüssig. Zum anderen geht es noch kürzer.
ausgabe = not geheim;
Dadurch dass man die Abfrage eingespart hat, könnte es sogar zu einer Steigerung der Performance kommen. Dies hängt aber vom Compiler ab.
Beispiel 2 (Python):
l = list() for item in dic: if 'key' in item: l.append(item['key'])
Python bietet die Möglichkeit von online-Befehlen. Damit lässt sich die for-Schleife vereinfachen.
l = [ item['key'] for item in dic if 'key' in item ]
Diese paar Zeilen summieren sich in einem größeren Projekt und machen es so übersichtlicher.
Die Struktur
Trotz der Optimierung ist es nicht möglich ein Projekt mit nur einer Zeile Code zu erstellen. Für größere Projekte muss der Quellcode in mehrere Dateien aufgeteilt werden. Wichtig dabei ist die Ordnerstruktur des Projekts. Dies ist häufig von dem Projekt und der Programmiersprache abhängig. Einige Aspekte lassen sich aber ganz allgemein festhalten.
Ein Projekt gehört in ein Verzeichnis
Alle Dateien eines Projekts gehören an einen Ort. Wenn Funktionen ausgelagert werden, müssen diese unabhängig von dem Projekt behandelt werden. Die ausgelagerten Funktionen werden somit zu einem eigenen Projekt, einer Bibliothek. Diese wird dann in der Entwicklungsumgebung installiert und kann so in dem ursprünglichen Projekt verwendet werden.
Gleichmäßig verteilen
Es werden im Laufe der Entwicklung immer mehr Dateien erstellt. Diese sollten sich auf mehrere Unterverzeichnisse aufteilen. Die Aufteilung der Dateien sollte dabei gleichmäßig erfolgen. Das hat zwei Vorteile, zum einen ist es übersichtlich, aber zum anderen wird so auch die Last verteilt. In der Regel bedeutet mehr Quellcode auch mehr Rechenzeit. Ist die Rechenzeit gleichmäßig verteilt, ist die Wahrscheinlichkeit das es zum Überlasten einer Komponente führt, geringer.
ReadMe-Datei
Wenn ich ein Projekt finde, was keine ReadMe-Datei besitzt, wird es von mir ignoriert. Diese Datei verschafft dem Entwickler einen Überblick. Ohne diese Datei sind die Funktionen der anderen Dateien unbekannt. Der Einstig in das Projekt fällt so sehr schwer. Neben der ReadMe-Datei ist eine umfangreichere Dokumentation von Vorteil. Denk immer daran, dass andere Leute später mit deinem Projekt arbeiten. Auch wenn es nur dein zukünftiges Ich ist.
Namen
Beim ersten betrachten des Projekts sieht man nur die Namen der Ordner und Dateien. Diese sollten so aussagekräftig wie möglich sein.
Gleiches zu Gleichem
Du solltest verschiedenen Dateitypen nicht miteinander mischen. Die Icons gehören nicht in den gleichen Ordner wie der Quellcode. Werden beim Kompelieren der Dateien erzeugt, dann sollten diese in einen separaten Ordner erstellt werden.
Zusammenfassung
Dies waren in meinen Augen die wichtigsten Punkte. Für mich ist es wichtig, dass der Quellcode kompakt ist. Es gibt nichts schlimmeres als überflüssige Kommentare. Aber vielleicht siehst du das ja ganz anders? Auf GitHub liegt auch ein von mir geschriebener Quellcode, der leider nicht nach diesen Regeln verfasst ist. Aber wie heißt es so schön: Jeder hat irgendwo eine Leichen im Keller.