Codestil

[Xin]

Hier findet sich ein Vorschlag zum Codestil.

Grundsätzlich steht dieser zur Diskussion, allerdings grenze ich die Diskussion auf eine Woche ein (bis 12.Juli), was immer dann da steht gilt als verbindlich (ab 13. Juli) für das Repository.
Das bedeutet nicht, dass keine Erweiterungen mehr folgen könnten. Auch Änderungen sind nicht ausgeschlossen - aber ab dann eher unwahrscheinlich.

Dieser Thread ist für Rückfragen oder auch (begründete) alternative Vorschläge.
Viel Spaß beim Zerfleischen

[cloidnerux]

Es gäbe da nur eine Sache, die ich nicht so toll finde, nämlich lange Funktionen mit eingeschobenen Kommentaren.
Es ist viel Sinnvoller eine private Hilfsfunktion zu schreiben und den Hauptalgorithmus zu verkürzen. Jede Hilfsfunktion hat dann nur 1 Aufgabe, sollte Sinnvoll benannt sein und vor der Funktion als Doxygen Kommentar stehen. Kommentare innerhalb einer Funktion sollten meiner Ansicht nach nur dazu dienen, Stellen für einen Aufarbeitung zu markieren, in dem Zusammenhang sollte auch die Richtlinie stehen, das Funktionen nicht länger als 1 Bildschirmseite sind.

Mit 2 Leerzeichen als einrücken kann ich Leben, auch wenn ich es nicht so gewohnt bin.
Müssen die Kommentare nur Doxygen-kompatibel sein oder sind diese auch an einer Richtlinie gebunden?

[Xin]

Es gäbe da nur eine Sache, die ich nicht so toll finde, nämlich lange Funktionen mit eingeschobenen Kommentaren.
Es ist viel Sinnvoller eine private Hilfsfunktion zu schreiben und den Hauptalgorithmus zu verkürzen.

Da kann man geteilter Meinung sein.

Ich selbst bin dafür, Funktionen dann zu schreiben, wenn sie Redundanz verringern. Ansonsten kann ich mit langen Funktionen leben. Wenn Funktionen nur inline reinkopiert werde, kann ich sie gleich an der betreffenden Stelle lassen und auch falten. Ansonsten muss man abwägen, ob man eine Klasse mit Methoden aufbläht, die nur ein einziges Mal gerufen werden.
Das bedeutet, dass man mehr dokumentieren muss und in der Dokumentation um Methoden herumlesen muss, die im Prinzip für die Verwendung der Klasse nicht interessieren.

Jede Hilfsfunktion hat dann nur 1 Aufgabe, sollte Sinnvoll benannt sein und vor der Funktion als Doxygen Kommentar stehen. Kommentare innerhalb einer Funktion sollten meiner Ansicht nach nur dazu dienen, Stellen für einen Aufarbeitung zu markieren, in dem Zusammenhang sollte auch die Richtlinie stehen, das Funktionen nicht länger als 1 Bildschirmseite sind.

Es spricht nichts dagegen, Funktionen kurz zu halten. Ansonsten sind sind die Kapitel letztendlich das, was Du in einzelne Funktionen packen würdest.

Müssen die Kommentare nur Doxygen-kompatibel sein oder sind diese auch an einer Richtlinie gebunden?

Kommentare sind Kommentare, sie sollten sinnvoll sein, aber letztendlich kannst Du schreiben, was Du wichtig findest.
Doxygen dokumentiert. Mit Doxygen dokumentierst Du, wofür Du die Funktion geschrieben hast, in Kommentaren, wie Du etwas geschrieben hast und was man aus dem Quelltext nicht sofort herauszulesen ist.

[Kerli]

So ganz gefällt mir der Codingstandard noch nicht. Erstens ist er teilweise unnötig mehrdeutig und auch noch etwas unvollständig:

Objektorientierte Symbole (zu einer Klasse zugehörig) werden groß mit Camelcase geschrieben, das gilt für Konstanten, Variablen, wie auch für Methoden.

Warum? Ich finde es deutlich übersichtlicher wenn man auf den ersten Blick sieht ob es sich um eine Variable, einen Typ, eine Methode oder eine Konstante handelt. Nachdem auch noch Typen und in bisherigen Codeteilen Namespaces auch Camelcase benannt werden ist hier eigentlich gar keine Unterscheidung möglich. Ich hab einmal begonnen in meine Wiki meinen Codingstandard zu dokumentieren. Bis jetzt hat er sich eigentlich als recht gut und leicht lesbar bewährt.

Bei Funktionen (außerhalb von Klassen) sind mir auch zwei Benennungsmöglichkeiten aufgefallen. Einerseits zb. 'dosomething' wo alles klein geschrieben ist und andererseits zb 'doNothing' mit Camelcase und am Anfang klein. Ich würde letzteres bevorzugen.

Was ist mit Namespaces? Im bisher eingecheckten Code ist es entweder Camelcase oder komplett in Großbuchstaben. Normalerweise bevorzuge ich komplette Kleinschreibung damit man es von Typen unterscheiden kann. So weiß man bei gui::SOME_CONSTANT sofort das diese Konstante aus dem Namespace gui kommt und nicht wie GUI::SOME_CONSTANT aus der Klasse GUI.

Und was ist mit Template Parametern? Mein Vorschlag gleich wie Klassen benennen. Also vollständig Camelcase.

Ein Punkt der eventuell auch noch zu ergänzen wäre ist das Fangen von Exceptions. Das sollte immer per Referenz passieren, da nur so Polymorphismus korrekt funktioniert und man Exceptions bei Bedarf auch erweitern kann. Außerdem sollten alle neuen Exceptions von std::exception bzw. einer davon abgeleiteten Klasse ableiten (zb. std::runtime_error).

[Xin]

So ganz gefällt mir der Codingstandard noch nicht. Erstens ist er teilweise unnötig mehrdeutig und auch noch etwas unvollständig:

Wo ist er mehrdeutig?

Objektorientierte Symbole (zu einer Klasse zugehörig) werden groß mit Camelcase geschrieben, das gilt für Konstanten, Variablen, wie auch für Methoden.

Warum? Ich finde es deutlich übersichtlicher wenn man auf den ersten Blick sieht ob es sich um eine Variable, einen Typ, eine Methode oder eine Konstante handelt.

Wo ist der Unterschied?
Die Frage mag Dir merkwürdig vorkommen, aber Variable, Konstante, Methode oder Typ - in meinen Augen ist da kein Unterschied.

Variablen können const sein, dann sind es Konstanten. Watt nu?
Wenn Parameter const übergeben werden, so sind es lokale Konstanten, die als Parameter reinkommen. Klein, Groß, komplett in Kapitalen?
Eine Methode ist schlussendlich auch nichts anderes als eine Variable, eben ein Zeiger auf eine Funktion. Variable, Konstante und Funktion haben einen Typ. Wenn ein Typ in ein Template kommt, so er eine Konstante. Wenn ich den Typ dynamisch abfrage, so ist er eine Variable. Wenn der Typ ein Funktor ist, so ist die Variable eine Funktion. Ist ein Funktionszeiger eine Funktion oder eine Variable? Und wenn er const ist, dann ist er ein MACRO?

Hier verschwimmen Grenzen. Im Nebel Grenzen zu fordern führt in meinen Augen dazu, dass man sich im Grenzzaun verheddert. Ich unterscheide zwischen lokal/statisch und Member/Dynamisch, bzw. PRÄPROZESSOR. Ansonsten kommen in allen Fällen Werte eines Datentyps zurück - egal, ob ich das als Funktion, Typ, Variable oder Konstante angeben habe.
Grundsätzlich ist bei mir soviel wie möglich konstant. Entsprechend müsste ich fast alles groß schreiben.

Nachdem auch noch Typen und in bisherigen Codeteilen Namespaces auch Camelcase benannt werden ist hier eigentlich gar keine Unterscheidung möglich. Ich hab einmal begonnen in meine Wiki meinen Codingstandard zu dokumentieren. Bis jetzt hat er sich eigentlich als recht gut und leicht lesbar bewährt.

Lese ich mir gerne durch.

Bei Funktionen (außerhalb von Klassen) sind mir auch zwei Benennungsmöglichkeiten aufgefallen. Einerseits zb. 'dosomething' wo alles klein geschrieben ist und andererseits zb 'doNothing' mit Camelcase und am Anfang klein. Ich würde letzteres bevorzugen.

Wo gibt es 'dosomething()'? Das wäre ein Fehler.

Was ist mit Namespaces? Im bisher eingecheckten Code ist es entweder Camelcase oder komplett in Großbuchstaben. Normalerweise bevorzuge ich komplette Kleinschreibung damit man es von Typen unterscheiden kann. So weiß man bei gui::SOME_CONSTANT sofort das diese Konstante aus dem Namespace gui kommt und nicht wie GUI::SOME_CONSTANT aus der Klasse GUI.

Camecase, Abkürzungen bleiben groß.

Und was ist mit Template Parametern? Mein Vorschlag gleich wie Klassen benennen. Also vollständig Camelcase.

In meinem Verständnis sind es lokale Variablen => klein.

Ein Punkt der eventuell auch noch zu ergänzen wäre ist das Fangen von Exceptions. Das sollte immer per Referenz passieren, da nur so Polymorphismus korrekt funktioniert und man Exceptions bei Bedarf auch erweitern kann. Außerdem sollten alle neuen Exceptions von std::exception bzw. einer davon abgeleiteten Klasse ableiten (zb. std::runtime_error).

Lass uns den Exception-Bereich in cpp: erstmal fertig schreiben...

Dass Exceptions als Referenz eingefangen werden kann man gerne dazu als Hinweis schreiben.

[Kerli]

Wo ist er mehrdeutig?

Das mehrdeutig hat sich auf die gleiche Benennung unterschiedlicher Symboltypen bezogen.

Variablen können const sein, dann sind es Konstanten. Watt nu?

Ja, dann sind es Konstanten die ich dementsprechend in Großbuchstaben schreibe. Ob Konstanten durch enum oder const zustandekommen unterscheide ich nicht.

Wenn Parameter const übergeben werden, so sind es lokale Konstanten, die als Parameter reinkommen. Klein, Groß, komplett in Kapitalen?

Klein, da ich bei Parametern keine Unterschiede mache. Außerdem sind es erst zur Laufzeit Konstanten bzw. dort auch nur innerhalb der entsprechenden Funktion. (Theoretisch könnte man das ja auch mit einem const_cast umgehen, was bei echten Konstanten zu undefiniertem Verhalten führen würde)

Eine Methode ist schlussendlich auch nichts anderes als eine Variable, eben ein Zeiger auf eine Funktion.

Schlussendlich schon, aber hier geht es um die Verwendung und nicht um das was der Compiler daraus macht.

Ist ein Funktionszeiger eine Funktion oder eine Variable?

Ein Funktionszeiger ist eine Variable mit der Adresse einer Funktion. Funktionen sind wirklich nur reine Funktionen oder Methoden. Also eine Speicherstelle auf die man den Programmzähler setzen kann und dort weiterer Programmcode liegt den man ausführen kann.

Und wenn er const ist, dann ist er ein MACRO?

Nein, siehe oben. Konstanten sind nur Konstanten wenn sie bereits zur Kompilierzeit konstant sind.

Wo gibt es 'dosomething()'? Das wäre ein Fehler.

http://proggen.org/doku.php?id=project: ... leerzeilen

Und was ist mit Template Parametern? Mein Vorschlag gleich wie Klassen benennen. Also vollständig Camelcase.

In meinem Verständnis sind es lokale Variablen => klein.

Also ich würde sie eher als Datentypen ansehen und dementsprechend Camlecase schreiben. zb:

Code: Alles auswählen

template<typename Type> Type someFunction(Type arg);

[Xin]

Variablen können const sein, dann sind es Konstanten. Watt nu?

Ja, dann sind es Konstanten die ich dementsprechend in Großbuchstaben schreibe. Ob Konstanten durch enum oder const zustandekommen unterscheide ich nicht.

Code: Alles auswählen

MyStruct MyStruct::METHOD( MyStruct const PARAM_A, MyStruct const PARAM_B ) const

Und wie konsequent bist Du mit Deinen Unterscheidungen, oder bist Du weniger mehrdeutig?

Wenn Parameter const übergeben werden, so sind es lokale Konstanten, die als Parameter reinkommen. Klein, Groß, komplett in Kapitalen?

Klein, da ich bei Parametern keine Unterschiede mache. Außerdem sind es erst zur Laufzeit Konstanten bzw. dort auch nur innerhalb der entsprechenden Funktion. (Theoretisch könnte man das ja auch mit einem const_cast umgehen, was bei echten Konstanten zu undefiniertem Verhalten führen würde)

Nein, es führt zu identischem Verhalten: Die Konstante wird verändert, was dazu führt, dass zukünftige Zugriffe auf die Konstante ein nicht konstantes Ergebnis liefern.
Wenn Du Glück hast, hast Du Speicherschutz und dsa Programm fliegt Dir um die Ohren.

Eine Methode ist schlussendlich auch nichts anderes als eine Variable, eben ein Zeiger auf eine Funktion.

Schlussendlich schon, aber hier geht es um die Verwendung und nicht um das was der Compiler daraus macht.

Verwendest Du Variablen anders als Funktionen? Und wenn ja... warum?

Ist ein Funktionszeiger eine Funktion oder eine Variable?

Ein Funktionszeiger ist eine Variable mit der Adresse einer Funktion. Funktionen sind wirklich nur reine Funktionen oder Methoden. Also eine Speicherstelle auf die man den Programmzähler setzen kann und dort weiterer Programmcode liegt den man ausführen kann.

Das kann kompliziert werden bei Gettern und Settern. Und bei Properties - die C++ selbst so noch nicht unterstützt - sowieso.

Und was ist mit Template Parametern? Mein Vorschlag gleich wie Klassen benennen. Also vollständig Camelcase.

In meinem Verständnis sind es lokale Variablen => klein.

Also ich würde sie eher als Datentypen ansehen und dementsprechend Camlecase schreiben. zb:

Code: Alles auswählen

template<typename Type> Type someFunction(Type arg);

Camelcase grunsätzlich, SomeFunction oder someFunction je nach Position (dynamisch/statisch).
typename Type wäre bei mir grundsätzlich typename type, da type eher einer lokalen Variable entspricht als eines festgelegten Typs. Es ist eine statische Variable vom Typen typename, die einen Typ repräsentiert. Wenn Du Typen und Variablen so dringend trennst, dann wird das mit typename Type ambivalent.

[cloidnerux]

Öhm, können wir die Leerzeichen zur Einrückung auf 4 erhöhen?
Dann muss ich nicht VS umstellen, es ist Übersichtlicher, Funktionen mit Tiefen Einrückungen sollte man mit Wächtern vermeiden und bei langen Funktionen die Argumente besser untereinander schreiben.

[fat-lobyte]

Eine Anmerkung:

es sollte geklärt werden, welche Zeilenendungen zu verwenden sind, also LF (Linux), CR/LF (Windows) oder CR (Mac). Im Moment sieht es damit ziemlich durcheinander aus, denn jeder commitet gerade wie sein Editor zufällig eingestellt ist.
Interessant dazu könnte noch eine SVN Eigenschaft sein: http://www.zope.org/DevHome/Subversion/ ... ineEndings

Vielleicht sollte auch noch die Kodierung einigen. Hier würde sich UTF-8 anbieten, da es doch einigermaßen protabel sein sollte.


Wenns noch interessant ist, kann man darüber diskutieren ob Kommentare Englisch oder Deutsch sein sollen.

[Xin]

Öhm, können wir die Leerzeichen zur Einrückung auf 4 erhöhen?
Dann muss ich nicht VS umstellen, es ist Übersichtlicher, Funktionen mit Tiefen Einrückungen sollte man mit Wächtern vermeiden und bei langen Funktionen die Argumente besser untereinander schreiben.

Ich lasse das hier zur Diskussion frei.

Wächter können nicht immer sinnvoll platziert werden und tiefe Einrückungen sind in meinem Stilverständnis unerwünscht, aber kein Problem.
Ich ändere einen guten Algorithmus nicht, weil er mir zu weit rechts steht. Auch dafür schätze ich die nur zwei Stellen.

Mein VS steht auf 2 Stellen. Es muss so oder so einer umstellen.
Möchtest Du Funktionen mehrzeillig rufen, solltest Du die Argumente direkt unterhalb schreiben. Hier ist die Einrückung durch den Funktionsnamen
vorgegeben. Ich trage das jetzt gleich noch nach.

Ich habe früher auch auf 4 Stellen programmiert. Ich habe mich inzwischen eines besseren belehren lassen. Vielleicht geht Du in eine ähnliche Richtung.
Ich lasse das Thema offen, falls sich andere melden, die ihre Meinung dazu kundtun.

Vielleicht sollte auch noch die Kodierung einigen. Hier würde sich UTF-8 anbieten, da es doch einigermaßen protabel sein sollte.

Grundsätzlich sollte Subversion das Lineencoding vereinheitlichen. Ich weiß noch nicht, wieso das bei Cloidnerux nicht funktioniert hat.

Wenns noch interessant ist, kann man darüber diskutieren ob Kommentare Englisch oder Deutsch sein sollen.

Als Sprache für Implementation (also die Kommentare) und Dokumentation wird Englisch verwendet. Steht recht weit oben.