HomeControl Richtlinien
Aus iSysBus Doku
Dateiaufbau
Jede Datei enthält einen Header, der verschiedene Details enthält, wie z.B. den Autor, einen Copyright-Hinweis etc. Bestimmte Felder, wie beispielsweise $Id$ werden beim Commit ins Repository automatich eingetragen, allerdings ist es sehr wichtig, dass dazu "svn:keywords" in den Eigenschaften der Datei aktiviert wurde!
Code-Konventionen
Sehr wichtig bei der Erstellung des Programmcodes ist, dass dieser dokumentiert wird! Dabei werden alle Kommentare in englischer Sprache verfasst und im JavaDoc-Format geschrieben, damit die Programmdokumentation automatisch erstellt werden kann (siehe dazu diese Seite).
Da verschiedene Schreibweisen bei der Programmierung zulässig sind, aber eine Mixtur der Übersichtlichkeit abträglich ist, gibt es folgende Richtlinien, die möglichst eingehalten werden sollten:
Blockanfänge mit in die Anweisungszeile
Beispiel:
if (variable == true) {
...
}
anstatt
if (variable == true)
{
...
}
Leerzeichen vor und hinter Operatoren
Beispiel:
String var = "test";
for (int i = 0; i < 100; i++) {
...
anstatt
String var="test";
for (int i=0;i<100;i++) {
...
Kommentieren von Funktionen, Methoden und Klassen
/** * Kurzbeschreibung der Funktion * * @param a Ein Integer-Wert * @param s Ein konstanter Char-Pointer (für ...) * @see Test() * @see ~Test() * @see testMeToo() * @see publicVar() * @returns Kurzbeschreibung des Rückgabewerts */ int funktion(int a,const char *s);
Eine längere Beschreibung kann man in die Zeilen nach der Kurzbeschreibung setzen
/** * Kurzbeschreibung, eine Zeile. * Ab hier folgt eine längere Beschreibung, * die sich auch über mehrere Zeilen * erstrecken kann */
Kurze Kommentare (von Variablen, etc.)
/** * Eine public-Variable. * (optional: längere Beschreibung, siehe oben) */ int publicVar;
Alternativ dazu kann man einzeilige Kommentare verwenden, z.B. direkt hinter Variablen
/**
* Ein enum.
* Detailliertere Beschreibung...
*/
enum TEnum {
TVal1, /**< enum value TVal1. */
TVal2, /**< enum value TVal2. */
TVal3 /**< enum value TVal3. */
}
