Code-Konventionen

Aus TV-Browser Wiki
Version vom 1. September 2009, 22:00 Uhr von Bananeweizen⧼word-separator⧽⧼parentheses⧽ ⧼parentheses⧽
⧼revision-nav⧽
Wechseln zu: Navigation⧼comma-separator⧽Suche

Die folgenden Regeln sollten eingehalten werden, wenn jemand Quellcode für TV-Browser schreiben will.

Sie helfen dabei, den Quellcode einheitlicher und besser lesbar zu machen und ihn besser zu dokumentieren.

TV-Browser hält sich an die Java-Code-Konventionen. Die wichtigsten Regel daraus und Besonderheiten oder Abweichungen sollen im folgenden vorgestellt werden.


Bezeichner

Bezeichner sollten nach folgenden Regeln benannt werden:

  • Generell sollen Bezeichner auf Englisch benannt werden.
  • Klassennamen beginnen mit Großbuchstaben und gehen dann mit gemischter Groß-/Kleinschreibung weiter. Beispiel: ProgramFieldType.
  • Paket-Namen bestehen nur aus Kleinbuchstaben. Beispiel: util.ui.progress.
    Hinweis: TV-Browser verletzt aus historischen Gründen die Konvention, dass Paket-Namen mit der umgekehrten URL der Organisation beginnen (Z.B. tvbrowser.core anstatt net.sf.tvbrowser.core). Plugins können sich selbstverständlich an diese Konvention halten.
  • Variablen- oder Methodennamen fangen mit einem Kleinbuchstaben an und gehen dann mit gemischter Groß-/Kleinschreibung weiter. Beispiel: handleTvDataAdded. Bei TV-Browser beginnen Klassenvariablen (member variables) zur besseren Unterscheidung von lokalen Variablen mit einem m. Beispiel: mMarkIcon.
  • Konstanten (also Variablen eines Standard-Datentyps, die static final sind) bestehen nur aus Großbuchstaben und Unterstrichen. Beispiel: TEXT_FORMAT.

Code-Formatierung

Folgende Regeln gelten für die Formatierung des Quellcodes:

  • Generell sollten keine Tabstopps verwendet werden. Viele Leute verwenden unterschiedliche Tab-Weiten, so dass Tabstopps sehr schnell dazu führen, dass Einrückungen völlig zerrupft werden.
    Hinweis: In Eclipse kann man einstellen, dass statt Tabstopps Leerzeichen gesetzt werden (Unter Window->Preferences->Java->Code Style->Code Formatter->Edit->Use tab character)
  • Eingerückt wird mit zwei Leerzeichen.


Kommentare

  • Alle Kommentare sollen in Englisch verfasst werden.
  • Alle public Methoden, Konstruktoren oder Klassen bekommen einen Javadoc-Kommentar mit @param- und @return-Tags. Bei Klassen in devplugin, util und tvdataservice zusätzlich noch den @since-Tag.
    Hinweis: In Eclipse kann man einstellen, dass Warnungen gezeigt werden, wenn bestimmte Methoden nicht dokumentiert sind (Unter Window->Preferences->Java->Compiler->Javadoc).
  • Kommentare, die nur auf die überschriebene Methode der Super-Klasse verweisen, sind nicht erwünscht. Sie bringen keine Informationen und moderne IDEs können diesen Zusammenhang selbst besser zeigen.

Architektur

  • Außer Konstanten sollten alle Variablen private oder protected sein. Um anderen Klassen Zugriff zu ermöglichen, sollte eine Getter- und/oder Setter-Methode geschrieben werden.
  • Plugins sollen keine Abhängigkeiten (Imports) in das tvbrowser-Paket haben.
  • Es sollte generell keine Abhängigkeiten (Imports) zu konkreten Plugins geben. (Abhängigkeiten zum Paket devplugin sind natürlich erlaubt). Davon ausgenommen sind natürlich die eigenen Klassen eines Plugins.