Code-Konventionen

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.