Softwaretechnik/Studienprojekte/Beispiel Styleguide

Aus StudiWiki

< Softwaretechnik | Studienprojekte

Wechseln zu: Navigation, Suche

Styleguide, wie er bei IVY2 benutzt wurde

Styleguide basierend auf IVY1 Änderungen durch S. Grottel und OliverKopp Status: Freigegeben Version: 1.2

Änderungen:

2003-11-19 koppor Beispiel-Header eingefügt
2003-12-02 koppor
- \short und \param im Methoden-Beispiel-Header eingefügt
- "Änderungen" im Beispiel-Header durch "Changes" ersetzt
2003-12-19 koppor Unnötiges erweitertert

Inhaltsverzeichnis

1 Kennzeichnung von Änderungen
2 Kommentare
3 Was tun bei Verletzungen des Styleguides
4 Naming-Conventions
5 Programmiersprachenkonstrukte
6 Klassen und Objekte
7 Exceptions
8 Format des Codes
9 Triviales
- 9.1 Dateien
- 9.2 Anderes

[bearbeiten] Kennzeichnung von Änderungen

cvs commit-log:

 Zusammenfassung der Änderung

Im Header wird nichts mitgeführt - wird durch $Log$ und dadurch durch das Log im CVS gemacht
an jeder Routine, falls nicht direkt aus CVS-Log ersichtlich

\par Changes: - yyyy-mm-dd <login> <Änderung>

[bearbeiten] Kommentare

Doxygen bentutzen (siehe DoxyGen-Kommandos)
/* */ ist nur bei Headern (Klassen, Methoden) erlaubt, ansonsten immer // benutzen (auch bei mehrzeiligen Kommentaren)

[bearbeiten] Header jedes Files

In der ersten Zeile:

 /* $Id$ */

[bearbeiten] hpp: Header jeder Klasse

 
 /** 
  *  \author    <IVY1-Autor>
  *  \author 	<login>      (Aktueller Autor)
  *
  *  \short  	Aufbau der Zellenstruktur (Kurze Beschreibung der Klasse, ggf. \long benutzen)
  *
  *  \par Changes:
  *    $Log$
  */

Log wird automatisch von CVS generiert.

[bearbeiten] hpp: Methoden

 /**
  *  \short Kurze Beschreibung (Englisch)
  *
  *  \author benutzen, falls nicht Hauptautor des .[ch]pp-Files
  *
  *  Für jeden Parameter (falls Klärungsbedarf)
  *    \param <Name> <Beschreibung>
  *
  *  \pre  true   (durch Assertion prüfen)
  *
  *  \post true   (durch Assertion prüfen)
  *
  *  \todo 
  *     Beschreiben, was noch zu machen ist
  */

[bearbeiten] Unnötig

 * Im Header:
   * \par Letzte Änderung: mit $Date$ und $Author$, steht alles in $Id$ drin
   * \class: Doxygen kann den Klassennamen parsen: Redundante Information!
     (natürlich nur, wenn class X gleich darunter steht.
 * In Methoden:
   * \fn: Doxygen kann den Methodennamen parsen: Redundante Information!

[bearbeiten] Was tun bei Verletzungen des Styleguides

* Autor darauf hinweisen
* Falls das nicht geht (z.B. weil es schon im IVY-Source so war)
  # selbst korrigieren
  # bei größeren Sachen: QS benachrichtigen

[bearbeiten] Naming-Conventions

Englisch
- Bezeichner
- Routinen
- Filenamen
- Module
- einfach alles
keine Codierungen im Namen
- sog. ungarische Notation des Variablentyps, z.B. lpszName
- in VIS wegen Windows-API eingeschränkt erlaubt aber zu vermeiden.
Aussprechbare Namen oder eindeutige Abkürzungen

Typnamen beginnen mit einem Großbuchstaben
Variablennamen beginnen mit einem Kleinbuchstaben
Konstanten und Enumerations sind in CAPITALS geschrieben
- Mehrere Teile durch _ trennen
Methoden beginnen mit einem Kleinbuchstaben
Zusammengesetzte Bezeichner durch Großschreibung jedes weiteren Teils trennen (z.B. W'egstreckenFolge)
Substantive im Klassen-/Objektnamen als Singular
Funktionen, die Boole'sche Werte zurückliefern, beginnen mit "is".
getX/setX ist ausdrücklich erwünscht
Methoden, die ein Objekt erzeugen und zurückgeben beginnen mit "create" (Ausnamen sind z.B. getInstance() bei Singelton).

Falls ein Wort mehrere Bedeutungen hat: Nicht verwenden
- Ansonsten: immer nur in der einen Bedeutung verwenden
Bezeichner mit Laberfaktor vermeiden (information, data, system). Falls nicht möglich: konkretisieren
Bezeichner, die im real life eine andere, "natürliche" Bedeutung haben, nicht verwenden. (z.B. hp, ms, km, EUR, aldi, RL)

[bearbeiten] Programmiersprachenkonstrukte

Casts
- unnötige Casts grundsätzlich vermeiden
- C-Casts (N'ewType) Expression sind verboten'
- static_cast<N'ewType> Expression erlaubt
- dynamic_cast<N'ewType> Expression erlaubt
- const_cast<N'ewType> Expression verboten'
- reinterpret_cast<N'ewType> Expression verboten'
- Alle anderen Cast-Operatoren sind grundsätzlich verboten.
malloc und free sind verboten
union in Ausnahmefällen (Visualisierung) erlaubt
const wo möglich verwenden:
- in-Parameter bei Klassen: const Class param
- in-Parameter bei Typen: const Type& param

[bearbeiten] Klassen und Objekte

Es gibt keine freien Funktionen, d.h. Funtkionen können nur in Klassen und Strukturen (als Methoden) auftreten (static verwenden).
Keine Klasse ohne Namensraum

namespace Modulename {
}

Konstanten dürfen nur im Kontext von Klassendefinitionen existieren. In Ausnahmefällen im Namespace.
Besitzt eine Klasse dynamische Elemente, so müssen ein Copy-Konstruktor und ein Zweisungsoperator definiert werden
Die Basisklasse muss einen virtuellen Destruktor besitzen
Zuweisungsoperator
- Muss eine Referenz auf *this zurückliefern
- alle Datenelemente müssen zugewiesen werden
- Zuweisung an sich selbst muss überprüft werden
- Template

class Type {
public:
    Type();                            // Default-Constructor
    Type(const Type& type);            // Copy-Constructor
    Type& operator=(const Type& type); // Assignment-Operator
private:
    int dynamicElement;
};
      
Type::Type() {
    dynamicElement = 0
}

Type::Type(const Type& type) {
    dynamicElement = type.dynamicElement;
}

Type::Type& operator=(const Type& type) {
    if (&typ == this) {
        // handle error
    } else {
        dynamicElement = type.dynamicElement;
    }
    return *this;
}

[bearbeiten] Exceptions

In Konstruktoren dürfen bei geworfenen Excpetions keine Speicherlecks produziert werden.
In Destruktoren dürfen keine Exceptions geworfen werden
Kontrollfluss nicht über Exceptions
Einsetzen, wenn Problem nicht lokal behoben werden kann
- Log-Ausgabe?
Typfehler = Assertions, keine Exceptions

[bearbeiten] Format des Codes

79 Spalten Einrückung 4 Zeichen

    if (Bedingung) {
        <code>
    } else {
        <code>
    }

class/struct/void func (Vehicle vehicle, int speed) name {
    <code>
}

[bearbeiten] Triviales

[bearbeiten] Dateien

Header-Dateien:
- Endung .hpp
- Klassendeklarationen (mit enthaltenen Konstanten) und Typen
- #include-Guards verwenden
  - Name: INCLUDED_FILENAME_WO_EXTENSION_HPP

ifndef INLCUDED_COOL_HPP
define INCLUDED_COOL_HPP

<code>

endif

C++-Files:
- Endung .cpp
- Klassendefinitionen, Klassenvariablen

[bearbeiten] Anderes

Der ([1] Styleguide von geosoft) enthält Zusätzliches, was sich allerdings von selbst versteht. Bei Widersprüchen (z.B. der Formatierung des else bei if) ist der IVY2-Styleguide massgebend
Sichtbarkeitsbereiche so weit wie möglich einschränken
const wo möglich verwenden
Keine globalen Variablen verwenden (z.B. statt globaler Variable static Attribut)
Methoden, die etwas Unterschiedliches tun, tragen verschiedene Namen
Objekt immer per Referenz übergeben (wenn nicht möglich, dann Pointer und nur wenn Seiteneffekte ausgeschlossen werden müssen, Kopien übergeben)
Es ist nur öffentliche Vererbung erlaubt: class child : public parent
Ein Kind muss genauso wie sein Vater benutzbar sein

Von „http://studiwiki.informatik.uni-stuttgart.de/Softwaretechnik/Studienprojekte/Beispiel_Styleguide“