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.

[sp1nny]

Rider hatte zu dem Thema auch etwas gepostet, ist sogar Sticky: http://free-hack.com/ansi-c-c-c/4759...-standard.html

[DoS]

Ja, ist ganz nett. Allerdings denke ich, dass die meisten C++ler sich ein vernünftiges Buch gekauft haben, in dem so etwas drin steht. Zudem ist es bei mir so, dass ich mich im Zuge meines Informatikkurses schon stark mit Dingen, wie Variablenbezeichnung auseinander setzen musste.

Wie gesagt, die meisten hier haben ein vernünftiges Buch. Für die Anderen ist das bestimmt sehr interessant. Im .NET Forum wäre so ein "Tutorial" bestimmt noch besser angelegt. Wieso das so ist, kann sich ja jeder selbst denken .

Was man noch hinzufügen könnte:

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.

Mit freundlichen Grüßen
DoS

[aL1ien]

@DoS
Stimmt, eigentlich wäre es im .NEt Bereich wesentlich besser angesiedelt .
Ich behaupte mal, dass jeder, welcher anfängt zu programmieren, dies mithilfe eines Buches tut und man sieht, dass es relativ wenige beherrschen.

Danke für deine Ergänzung. Habe es hinzugefügt.

[Toastbrot]

Schön das jemand mal so eine Grundlage in einem Tutorial behandelt.

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

Meine Erfahrung mit solchen - ich nenne sie jetzt mal - Vorzeichen ist eigentlich, dass sie mir beim Programmieren helfen. Eben dank IntelliSense kann ich mir beim Druck von z.B. "i" alle Variablen vom Typ Integer anzeigen lassen. Falls ich mal vergesse, wie ich eine Variable genau genannt hab ist das sehr vorteilhaft und vor allem kommt man dadurch schneller vorran.

Übernehm am besten auch von DoS, dass Klassennamen groß geschrieben werden sollten. Das fehlt noch beim ersten Post. Und auch, dass Umlaute in Variablen- und Klassennamen vermieden werden sollten.

MfG

edit:// ich seh grad das mit den Klassennamen steht wohl da. Sorry ^^

[aL1ien]

Stimmt, über die Intellisense frage lässt sich streiten. Dies ist wohl Ansichtssache.
Welche IDE benützt du?

[breez]

Wenn man die ungarische Notation weg lässt, weil sie durch Intellisense teilweise ersetzt werden kann, macht man sich so gesehen von einer IDE abhängig.
Wenn man dann Teile des Quellcodes veröffentlichen will, kann man aber nicht davon ausgehen, dass alle eine IDE nutzen, die Intellisense unterstützt. Außerdem wäre eine Notation auch hilfreich, wenn der Code in Foren gepostet wird. Wenn ich bei Free-Hack einen Quellcode sehe, will ich diesen nicht erst in meine IDE einfügen.

Die ungarische Notation ist auch beim eigenen Projekt mit Intellisense-IDE sinnvoll, weil man sich den Code dann auch gut anschauen kann ohne, dass man für jede Variable und Funktion mit der Maus durch die Gegend fahren muss.

[EBFE]

Ganz nett finde ich die Java Code Conventions (ja, ich weiß, eigentlich der Todfeind jedes C++ Programmierers *g* ) aber das Ganze mal Systematisiert und imho gut durchdacht. Wenn man danach C# Code lesen muss, der nach MS "Standards" geschrieben wurde, merkt man den Unterschied sehr deutlich.
Code Conventions for the Java Programming Language
bzw
http://java.sun.com/docs/codeconv/ht....doc8.html#367
Wobei es natürlich noch auch die jeweilige Sprache angepasst werden muss (z.B bevorzuge ich es in "Low-Level" Sprachen die Variablen durch _ anstatt Großbuchstaben zu schreiben: bsp: "klein_buchstabe" vs "kleinBuchstabe", damit man Funktionen und Variablen besser unterscheiden kann).