BankAndCustomer
|
Um eine gemeinsame Entwicklung in C++ zu erleichtern, ist es sinnvoll, wenn Programmierrichtlinien eingehalten werden. Hier sind die wichtigsten Vorgaben für dieses C++-Projekt aufgeführt.
Für die einzelnen Typen von Bezeichnern gelten einheitliche Regeln.
Grundsätzlich soll für alle Bezeichner die englischer Sprache genutzt werden.
In der Regel soll jede Klasse in einer Header-Datei deklariert und in einer Quelltext-Datei definiert werden (ausnahmen sind Template-Klassen, Inline-Methoden und Structs). Beide Dateien bekommen die Klassenbezeichnung als Namen.
Sollten mehrere Klassen in einer Header-Datei deklariert und in einer Quelltext-Datei definiert werden, sollte ein aussagekräftiger Modulname für die Dateien gewählt werden.
C++ Header-Dateien und globale Typ-Dateien erhalten die Extension .h.
C++ Quelltext-Dateien erhalten die Extension .cpp.
Klassen-Namen werden grundsätzlich am Anfang mit einem Großbuchstaben eingeleitet.
Um eine Zuordnung zu einem Projekt bzw. zu einer Bibliothek zu signalisieren, können maximal 3 Buchstaben als Kürzel genutzt werden. Davon muss der erste ein Groß- und die weiteren beiden Kleinbuchstaben sein. Die folgende Klassenbezeichnung fängt wieder mit einem Großbuchstaben an. Der Name sollte so gewählt werden, dass der Job der Klasse klar wird. Wenn es sich um eine Bezeichnung aus mehreren Wörtern handelt, sind diese einzeln entsprechend der CamelCase-Notation mit anführenden Großbuchstaben zu schreiben ( z.B. 'GloBaseMaker').
Template-Klassen bekommen vor ihren Namen, nach dem Projekt- bzw. Bibliothek-Kürzel ein 'T' eingefügt (z.B. 'GloTOndemandSet').
Alternativ kann eine Zuordnung zu einem Projekt bzw. zu einer Bibliothek über einen Namensraum (namespace) realisiert werden. Für die Bezeichnung des Namensraums sollten maximal 3 Kleinbuchstaben als Kürzel genutzt werden ( z.B. 'glo::BaseMaker'). Die Wiederholung eines Projektkürzels vor dem Klassen-Namen sollte dann aber vermieden werden.
Die Attribute von Klassen werden grundsätzlich mit einem 'm_' (steht für Member) eingeleitet. Es folgt dann eine umstrittene und nicht ganz durchzuhaltende Kennzeichnung nach der ungarischen Notation gefolgt von einem aussagekräftigen Namen, welcher mit einem Großbuchstaben anfängt (z.B. 'm_sApplicationName' für einen String).
Die Methoden von Klassen werden grundsätzlich mit einem Kleinbuchstaben eingeleitet. Es sollte in der Regel ein Verb benutzt werden, welches die Dienstleistung der Methode beschreibt (z.B. 'loadIconPath'. Wenn Zustände einer Klasse abgefragt werden sollen, hat sich bewährt, die Methodenbezeichnung mit einem 'is' oder 'has' zu beginnen (z.B. 'isStored' oder 'hasConnection'
Globale Variablen werden grundsätzlich mit einem 'g_' (steht für global) eingeleitet. Es folgt dann eine umstrittene und nicht ganz durchzuhaltende Kennzeichnung nach der ungarischen Notation gefolgt von einem aussagekräftigen Namen, welcher mit einem Großbuchstaben anfängt (z.B. 'g_sGloVersion' für einen String).
Lokale Variablen werden grundsätzlich mit einem 't_' (steht für temporär) eingeleitet. Es folgt dann eine umstrittene und nicht ganz durchzuhaltende Kennzeichnung nach der ungarischen Notation gefolgt von einem aussagekräftigen Namen, welcher mit einem Großbuchstaben anfängt (z.B. 't_iErr' für eine lokale Int-Variable).
Parameter werden in der Regel mit einer umstrittenen und nicht ganz durchzuhaltende Kennzeichnung nach der ungarischen Notation eingeleitet, gefolgt von einem aussagekräftigen Namen, welcher mit einem Großbuchstaben anfängt (z.B. 'eLockMode' für einen Enum-Wert).
Um die Suche nach Inhalten zu vereinfachen, sind einige Datei-Typen vorgegeben bzw. vorgeschlagen.
Wie schon unter Dateinamen erwähnt. In der Regel soll jede Klasse in einer Header-Datei deklariert und in einer Quelltext-Datei definiert werden (ausnahmen sind Template-Klassen, Inline-Methoden und Structs). Beide Dateien bekommen die Klassenbezeichnung als Namen.
Sollten mehrere Klassen in einer Header-Datei deklariert und in einer Quelltext-Datei definiert werden, sollte ein aussagekräftiger Modulname gewählt werden.
Die globalen Konstanten, Enumerationen und Strukturen werden in einer Header-Datei untergebracht. Der Name dieser Datei sollte das Projekt- bzw. Bibliothekskürzel mit einem folgenden 'Types' sein ( z.B. 'GloTypes').
Wenn Konstanten, Enumerationen und Strukturen nur eine Klasse betreffen, ist immer abzuwägen, ob diese nicht in die jeweilige Klassen gehören.
Für ein Projekt globale Fehlerkodes werden in einer Header-Datei untergebracht. Der Name dieser Datei sollte das Projekt- bzw. Bibliothekskürzel mit einem folgenden 'Errors' sein ( z.B. 'GloErrors').
Eine ToListe 'ToDo.txt' kommt in das jeweilige C++ Projektverzeichnis. In dieser ToDo-Liste werden nach Manier eines Scrum-Backlogs einzelne Anforderungen und noch zu erledigende Dinge priorisiert aufgelistet.
Um das Erkennen von Inhalten zu vereinfachen, sind einige Formatierungen vorgegeben bzw. vorgeschlagen.
Jede Textdatei mit Sonderzeichen muss im UTF8-Format gespeichert sein, damit die Sonderzeichen einheitlich behandelt werden.
Jeder logische Abschnitt im Quelltext sollte eingerückt sein. Einrückungen erfolgen in Schritten von 2 Zeichen. Diese Einrückung soll nicht als Tabulatorzeichen definiert sein.
Die Zeichen '{' und '}' stehen immer alleine in einer Zeile. Klammerpaare stehen immer in einer Spalte. Es wird empfohlen, auch einzeilige Anweisungen in '{' und '}' einzuklammern. Beispiel:
Um die Übersichtlichkeit zu unterstützen, werden logische Einheiten durch Kommentare und Unterbrechungen mit Linien eingeteilt. Beispiel:
Die Zeilenlänge sollte 80 Zeichen nicht überschreiten. Es gibt Fälle, wo dieses nicht eingehalten werden kann.
Empfehlungen für Zeilenumbrüche, wenn die Zeilenlänge überschritten wird.
Bei einer umfangreichen if-Anweisung bzw. while- und do-while-Schleifen:
Einzelne logisch zusammenhängende Deklarationen und Zuweisungen sollten in der selben Spalte stehen.
Kommentare und Dokumentationen sind notwendig, um den Quelltext verständlich zu halten.
Kommentare im Quelltext sollten in englischer Sprache verfasst sein bzw. bei Gelegenheit übersetzt werden. Je nach Bedarf können Block- oder Zeilenkommentare genutzt werden.
Die Dokumentation soll in mehreren Sprachen vorhanden sein und den Vorgaben von doxygen genügen.
Die Dokumentation der C++ Projekte wird mittels doxygen realisiert. Hier wird nicht doxygen als solches beschrieben, sondern wie und wo es angewendet wird.
Wenn es eine sprachspezifische Dokumentation geben soll, wird der jeweilige Dokumentationstexte zwischen '\if german' (für deutsch) und '\endif' eingefasst. Für die englische Sprache wäre das z.B. '\if english' und '\endif'. Das soll ermöglichen, dass jeder Programmierer und jede Programmiererin unabhängig davon welche Sprache(n) beherrscht werden, die jeweiligen OpenSource-Produkte nutzen bzw. am Projekt mitarbeiten können.
Jede Header-Datei bekommt nach dem Include-Blocker einen Hinweis auf die Lizenz. Eine kurze Beschreibung kann mehrsprachig sein; der Lizenztext ist grundsätzlich englisch.
Beispiel für Klasse 'GloLocalThread'.
Der Datei- und Klassenname, der Autorenname und der copyright-Eintrag sowie der Projekt- bzw. Modulname werden angepasst.
Nach den ggf. nötigen Forward-Deklarationen und Includes direkt über der Klassen-Deklaration wird die Klasse beschrieben.
Beispiel für Template-Klasse 'GloTOndemandSet':
Der Beschreibungstext für Attribute wird direkt vor diesem wie im Beispiel dargestellt beschrieben.
Beispiel für ein Attribut 'GloObjID m_RefObjID':
Der Beschreibungstext für Aufzählungen wird wie im Beispiel dargestellt beschrieben.
Beispiel 1 für eine Enum 'EnWatchStyle':
Beispiel 2 für eine Enum 'EnOpenClose':
Der Beschreibungstext für Funktionen bzw. Methoden wird direkt vor dieser wie im Beispiel dargestellt beschrieben.
Beispiel für eine Methode 'insert(...)':