Richtschnur Codeformatierung

[aL1ien]

Ich sehe immer wieder seeehr schlechten Code auf FH. Darum habe ich mich ran gemacht und diese Richtschnur geschrieben:


Das ganze lässt sich auf OOP- sowie die Prozedurale-Programmierung anwenden

Allgemeines Erscheinungsbild


Wenn du Code deinem Ausbilder zeigst, der FERTIG sein soll, dann betrachte deinen Code als PRODUKT, welches du präsentieren willst.

Das heisst, es sollte gut aussehen: korrekte Einrückungen, kein auskommentierter Code, Code nach dieser Richtschnur formatiert etc.
Dass der Code kompilierfähig sein muss und das Programm funktionieren muss, versteht sich von selbst.

Dokumentation


Bei grösseren Aufgaben soll eine Dokumentation erstellt werden.
Diese soll den Arbeitsverlauf dokumentieren. Sie muss mindestens enthalten, was die grundlegenden Ideen der Lösung sind.

Die Dokumentation soll den Arbeitsverlauf begleiten. Es ist sinnlos, sie vollständig im Nachhinein zu erstellen. Zuerst analysiert man ein Problem und sucht nach Lösungen. Diese groben Lösungsideen sollten dokumentiert werden. Probleme bei der Implementation sollten ebenfalls dokumentiert werden. Die Probleme und ihre Lösung sollten genug ausführlich dargestellt werden, so dass auch nach Abschluss der Arbeit noch nachvollziehbar ist, was genau das Problem war.

Die Dokumentation soll knapp und präzise sein. Sie soll sauber formatiert und lesbar sein.


Kommentare


Kommentare müssen eine zusätzliche Information liefern. Kommentare, die genau das auf Deutsch beschreiben, was der Code macht, sind überflüssig.
z.b: int x; //Initialisere x
return x; //Gebe x zurück
sind überflüssig

Idealerweise beschreiben Kommentare das WIE, und zwar nur in solchen Fällen, in denen es nur schwer möglich ist, dieses WIE aus dem WAS (welches explizit durch die Codezeilen gegeben ist) zu extrahieren. Das bedeutet auch, Trivialcode braucht nicht kommentiert zu werden.

Funktionen


Allgemeines


Funktionen sind das Hauptstrukturelement der prozeduralen Programmierung.

Der Hauptgrund für eine Funktion sollte sein, dass ihre Funktionalität an mehreren Stellen im Code benötigt wird oder ein solcher Bedarf zumindest erwartet werden kann.

Es gibt auch Ausnahmen von dieser Regel: wenn eine Funktion sehr gross und damit unübersichtlich wird, kann es vertretbar sein, Teile davon in eigene Funktionen auszulagern, auch wenn diese Teile nicht wirklich von anderen Orten her angesprochen werden.




Name


Der Name soll auf die Aufgabe hindeuten, welche durch die Funktion gelöst wird.
Der Name soll konkret sein, aber im Normalfall sollte er nicht auf die tatsächliche Implementation hindeuten. Unglücklich sind zu allgemeine Namen wie „berechnen“ oder „ueberpruefen“.

Als allgemeines Schema kann man nehmen:
- der Name sollte ein Verb enthalten,
- der Name sollte ein Nomen enthalten.
- Das Verb gibt an, was die Funktion tut, das Nomen, womit sie es tut.


Header


Eine Funktion soll stets einen Kommentar-Header enthalten. Dieser steht über der Funktionsspezifikation.

Beispiel:


/************************************************** ******
* IstZahlVorhanden
* Parameter:
* zahl : die zu prüfende zahl
* Rückgabe : true, falls die zahl bereits vorhanden
************************************************** ********/

Dies gilt nur für selber spezifizierte Funktionen. Funktionen, die vom System kommen (z.B. main) brauchen nicht dokumentiert zu werden.


Seiteneffekte


Sie sind zu vermeiden. Der Rückgabewert sollte möglichst nur von den Eingabewerten abhängen. So erreicht man stabilere Programme.

Negativ-Beispiel:

int berechnePotenz( int exp )
{
return pow(gBase,exp);
}

Hier greift die Funktion auf eine globale Variable zu. Man kann dies anhand der Funktionssignatur nicht erkennen, und das ist schlecht. In Wirklichkeit müsste die Basis ein Eingabeparameter sein:

Positiv-Beispiel:

int berechnePotenz( int base, int exp )
{
return pow(base,exp);
}


Variablennamen

Nennt die Variablen anständig. Eine variable "a" oder "strRdr"(für einen Streamreader) zu nennen ist nicht vorteilhaft. Stellt euch vor, dass ihr den Programmierern auf der Welt euren Code zur Verfügung stellen möchtet. Der programmierer, welcher schliesslich mit eurem Code arbeitet, möchte sich NICHT lange in euren Code einlesen um zu verstehen was ihr genau macht. Das gleiche gilt für die Funktionen / Methoden.

Nehmen wir an, dass ihr einen Funktionsplotter machen möchtet und ihr dafür eine Funktion / Methode braucht, welcher Y aus X berechnet. So würdet ihr sie in Deutsch "Berchene Y aus X" nennen, daraus folgt, dass es logisch ist, dass man die Funktion "BerechneYAusX" nennt und nicht "brchnWrtYX". Ihr gewinnt durch möglichst kurze Methodennamen NICHTS, im gegen teil, es macht es euch nur noch schwerer.

beispiel:

vector<string> getSeparateStringsFromDelimString( const string& text, const string& delim ) 

string getStringWithDelimFromVector( vector<string> stringWithouthDelim,string delim )

Hier erkenne ich sofort anhand des Funktionnamens was diese Funktion eigentlich macht ohne in den Code zu schauen. Ist das nicht toll?

Man nimmt aus der Aufgabenstellung einen Satz. Diesen Satz untersucht ihr nach Nomen und gliedert ihn anschliessend. Bei genauerer Betrachtung fällt einem auf, dass die Klassen, welche ihr später machen werdet, im großenteil die Nomen des Satzes sind. Ein Adjektiv beschreibt lediglich eine Handlung.

Versucht nicht, den Programmcode so kryptisch als möglich aussehen zu lassen. IHR GEWINNT DADURCH KEINEN VORTEIL.


Kommen wir nun zum letzten Teil:

Nennt die Variable nie "iSumme"(i für einen Integer),"strText"(für einen String),"pIrgendwas"(für einen Zeiger). Dies brauchte man früher, also man die modernen Entwicklungsumgebungen noch nicht gehabt hat. Heute sieht man ganz leicht anhand der Itelisense von welchem Typ eine Variable ist. Somit ist dies überflüssig



zum Schluss noch ein Zitat von mir aus einem anderen Thread:

Wir hatten bei uns in der Firma viele Leute wie dich. Etwas dahin geschludert, hauptsach es funktionierte. Leider haben sie nicht daran gedacht, dass auch andere Leute damit arbeiten müssen. Die Wartungszeit / Entwicklungszeit hat sich dabei enorm erhört. Zudem hast DU ja geschrieben, dass man ihn für andere Zwecke anpassen darf. Nur wie soll man das machen, wenn man sich erstmal 1h in den Code einleses / debuggen muss, bis man ihn versteht? Dann schreibt man es in der Zeit lieber neu, dafür sauber.

Nachtrag von DoS:

Methoden- und Variablennamen sollten generell immer klein anfangen und bei einem weiteren Wort am Anfang groß geschrieben werden. Beispiel: "amplitudenBereichPruefen". Man sollte allerdings darauf achten, dass die Namen nicht zu lang werden, wie es hier gerade schon fast der Fall war. Ihr könnt natürlich auch abkürzen, so lange der Sinn trotzdem klar ist. So wird zum Beispiel nicht Parameter geschrieben, sondern "param".
Objekte beginnen wie Variablennamen übrigens mit einem kleinen Buchstaben. Klassennamen hingegen mit Großbuchstaben.

Außerdem bin ich auch ein Freund des Einrückens (ich ziehe Tab vor):

  [...]
{
     this.var = var;
}
[...]

In diesem Beispiel geht es nur um das Einrücken. Dies wird besonders dann deutlich, wenn man mit Schleifen arbeitet. Durch das Einrücken bekommt man eine schöne Übersicht, was wozu gehört.