Programmierrichtlinien für C/C++

Transkript

1 Fachhochschule Vorarlberg Programmierrichtlinien für C/C++ Autor: Verantwortlicher: Status: Wolfgang Auer Wolfgang Auer Draft Review Accepted Version: 1.1, , Seite 1 / 9

2 Versionshistorie Version Datum Autor Bemerkung Wolfgang Auer Ursprüngliche Version Wolfgang Auer Anweisungsformatierung hinzugefügt Wolfgang Auer Kommentar-Konventionen hinzugefügt, C und C++ zusammengefügt Wolfgang Auer Released Wolfgang Auer Korrektur Beispiel Formatierung 1.1, Seite 2 / 9

3 Einleitung Dieses Dokument fasst ausschließlich die für die Lehrveranstaltungen des Department of Computer Science notwendigen Programmierrichtlinien für C/C++ zusammen. Stellen, an denen sich die Richtlinien für C und C++ unterscheiden, sind als solche gekennzeichnet. Wozu Programmierrichtlinien? Das Vorhandensein und vor allem das Einhalten von Programmierkonventionen ist aus verschiedenen Gründen wichtig: 80% der Gesamtkosten eines Softwaremoduls liegen in der Wartung Der Entwickler ist nicht immer auch die Person, die ein Programm wartet Programmierkonventionen erhöhen die Lesbarkeit von Code wodurch der Einarbeitungsaufwand von anderen Entwicklern wesentlich verringert werden kann. Die Fehlersuche im Programm wird erleichtert. usw. Dateinamen C/C++ unterscheidet zwei Dateitypen, die die folgenden Endungen verwenden: Dateityp Dateiendung Header-Datei.h Implementierungs-Datei.c (C-Code).cpp (C++ - Code) 1.1, Seite 3 / 9

4 Datei-Organisation Eine Datei besteht aus mehreren Abschnitten, die durch Leerzeilen getrennt sind und mit optionalen Kommentaren versehen werden können. Sowohl Header- als auch Implementierungs-Dateien sollten 2000 Zeilen nicht überschreiten. Header-Dateien 1 /* filename.h * * author * date * * information concerning class ClassName */ #ifndef FILENAME_H #define FILENAME_H #include <...> #include... #include... class...; enum... typedef... struct... extern... class ClassName : public SuperClassName { private: private Komponenten protected: Schnittstelle für Subklassen public: Schnittstelle für Klienten und Subklassen ; // ClassName #endif /* end of filename.h */ 1. Jede Header-Datei beginnt mit einem Kommentar, in dem der Autor, das Erstellungsdatum der Datei und alle Namen der definierten Klassen bzw Funktionen angeführt werden. 2. Include-Guard, um die mehrfache Einbindung von Header-Dateien zu verhindern 3. An dieser Stelle werden weitere Header-Dateien eingebunden, die Deklarationen enthalten, die zwingend bekannt sein müssen. Bei den zu inkludierenden Headern unterscheiden wird (1) Standard-Header-Dateien, (2) Bibliothek-Header-Dateien und (3) projektspezifische Header-Dateien 1.1, Seite 4 / 9

5 4. (Nur C++) Vorwärtsdeklaration von Klassen, die ausreicht, wenn nur Zeigerbzw. Referenzen dieser Klassen im Header verwendet werden. 5. Deklaration der öffentlichen Typen 6. Deklaration von Funktionen und Variable, die in einem anderen Modul definiert werden. 7. (Nur C++) Deklaration der Klassen Implementierungs-Dateien 1 /* filename.c or.cpp * * author * date * * information concerning implementation */ #include <...> #include... #include... #include filename.h enum... typedef... struct... class (C++ only) int... static ClassName::ClassName() {... /* end of filename.c or.cpp */ 1. Jede Implementierungs-Datei beginnt mit einem Kommentar, in dem der Autor, das Erstellungsdatum der Datei und die Funktion der Klassen oder des Moduls kurz erklärt wird. 2. In der Include-Sektion werden für die Implementierung benötigten Standard-Includes, Bibliothek-Includes, Projektspezifische-Includes und dem include der entsprechenden Deklarationsdatei 3. Deklaration der privaten Datentypen 4. Globale Daten, die exportiert werden und daher in der zugehörigen Header-Datei als extern deklariert wurden. 5. Definition der globalen privaten Dateien 6. Implementierung aller Methoden und Funktionen 1.1, Seite 5 / 9

6 Formatierung Einrückung Neue Blöcke werden mit je 4 Leerzeichen (keine Tabulatoren verwenden) eingerückt. string GetName() { if (m_name == null) { return No name ; return m_name; Zeilenumbruch Eine Zeile, die länger als 80 Zeichen lang ist, wird unter Beachtung der nachfolgenden Empfehlungen umgebrochen: Umbruch nach einem Komma Umbruch vor einem Operator Ein Ausdruck wird unter dem Anfang des umgebrochenen Ausdrucks fortgesetzt. Sollten die obigen Regeln die Lesbarkeit zu sehr beeinträchtigen, erfolgt eine Einrückung von 8 Leerzeichen Beispiel eines Methoden- bzw. Funktionsaufrufs: SomeMethod(longExpression1, longexpression2, longexpression3, longexpression4, longexpression5); Zeilenumbruch bei arithmetischen Ausdrücken: longname1 = longname2 * (longname3 + longname4 - longname5) + 4 * longname6; // PREFER longname1 = longname2 * (longname3 + longname4 - longname5) + 4 * longname6; // AVOID Zeilenumbrüche von if-anweisungen sollten generell 8 Leerzeichen verwenden, um die nachfolgenden Anweisungen deutlich erkennen zu können. //Don t use this indentation if ((condition1 && condition2) (condition3 && condition4)!(condition5 && condition6)) { //Bad wraps DoSomethingAboutIt(); //make this line easy to miss //Use this indentation instead if ((condition1 && condition2) (condition3 && condition4)!(condition5 && condition6)) { DoSomethingAboutIt(); Beispiel einer Methoden-Deklaration: //Indent 8 spaces to avoid very deep indents SomeType SomeOtherType::HorkingLongMethodName(int anarg, string anotherarg, string yetanotherarg) { 1.1, Seite 6 / 9

7 Leerzeilen Die Verwendung von Leerzeilen zur Trennung von Blöcken mit unterschiedlicher Funktionalität erhöht die Lesbarkeit des Quelltextes. Zwei Leerzeilen sollen verwendet werden zwischen: Abschnitten einer Quelltext-Datei Klassen- und Schnittstellendefinition Eine Leerzeile wird verwendet: zwischen Methoden bzw. Funktionen zwischen lokalen Variable einer Methode/Funktion und der ersten Anweisung vor einem Block oder einem Einzeilen-Kommentar Zwischen logischen Abschnitten innerhalb einer Methode oder Funktion Anweisungen Anweisungen werden wie folgt formatiert: if-anweisung if (condition) { if (condition) { else { if (condition) { else if (condition) { else { //AVOID! This omits the braces{! if (condition) statement; for-anweisung for (initialization; condition; update) { do-while-anweisung do { while (condition) switch-anweisung switch (condition) { case ABC: /* falls through */ case DEF: break; case XYZ: break; default: break; //empty for loop for (initialization; condition; update) ; while-anweisung while (condition) { //empty while loop while (condition) ; 1.1, Seite 7 / 9

8 Namenskonventionen Die einheitliche Namensgebung erleichtert das Verständnis eines Programms. Aus dem Namen kann auch die Funktion eines Bezeichners abgeleitet werden. Alle Namen werden in Englisch geschrieben! Funktions-, Typ-, Klassen- und Methodennamen beginnen mit einem Grossbuchstaben z.b. Stack, Push, StackPtr Bezeichner, die aus mehreren Wörtern bestehen, werden zusammengeschrieben. Jedes Wort, außer dem Ersten beginnt mit einem Grossbuchstaben Makronamen werden groß geschrieben. Namen, die aus mehreren Worten bestehen werden durch einen Unterstrich _ getrennt z.b. MAX_INT (Nur C++) Objektkomponenten (Attribute) beginnen mit m_ z.b: m_size, m_width, m_address,... Zeigervariable werden durch p gekennzeichnet z.b.: pstack, m_pstack (Zeiger als Objektkomponente) Statische Variable beginnen mit einen s z.b: snrofinstances,... Konstanten beginnen mit einem c z.b. cmaxint, cmaxnrofelement Globale Variable werden mit dem Präfix g gekennzeichnet z.b. gsize, gpaddress Kommentare Kommentare dienen dazu, Quelltext mit speziellen Implementierungsdetails zu versehen und somit die Verständlichkeit des Quelltextes zu erhöhen. Kommentare geben einen Überblick über den Quelltext und beinhalten Informationen, die nicht direkt aus dem Programmcode ersichtlich sind. Kommentare sollen nur Informationen umfassen, die zum Verständnis des Programms notwendig sind. Es wird zwischen Block-, Einzeilen-, Anfügungs- und Zeilenende-Kommentare (Nur C++) unterschieden. 1.1, Seite 8 / 9

9 Block-Kommentare Block-Kommentare werden zur Kommentierung von Dateien, Methoden, Funktionen, Datenstrukturen und Algorithmen verwendet. Block-Kommentare können am Anfang von Dateien, Methoden und Funktionen stehen oder auch innerhalb von Methoden und Funktionen. Block-Kommentare innerhalb einer Methode bzw. Funktion werden wie der Block, den sie beschreiben, eingerückt. Jedem Block-Kommentar geht eine Leerzeile voraus. /* * This is a block comment */ Einzeilen-Kommentare Kurze Kommentare können in einer einzelnen Zeile geschrieben werden. Einzeilen- Kommentare werden wie der Code, den sie beschrieben, eingerückt. Jedem Einzeilen-Kommentar geht eine Leerzeile voraus. if (condition) { /* This is a single-line comment */... Anfügungs-Kommentare Sehr kurze Kommentare können in der selben Zeile wie der Code, den sie beschreiben, geschrieben werden. Um die Lesbarkeit zu verbessern, sollen Anfügungs-Kommentare mit Hilfe von Leerzeichen vom Code getrennt werden. Werden innerhalb eines funktionalen Blocks mehrere Anfügungs-Kommentare verwendet, werden diese gleich ausgerichtet. if (a == 2) { return true; /* Special case */ else { return isprime(a); /* works only for odd a */ Zeilenende-Kommentare (Nur C++) Mit Hilfe der Zeilenende-Kommentare // können ganze Zeilen oder Teile einer Zeile auskommentiert werden. Obwohl dies möglich ist, sollten Zeilenende-Kommentare nicht zur Auskommentierung von ganzen Blöcken verwendet werden. if (foo > 1) { // Do a double flip else { return false; // Explain why here 1.1, Seite 9 / 9