Code-Konventionen
Aus TV-Browser Wiki
Version vom 1. September 2009, 22:00 Uhr von Bananeweizen⧼word-separator⧽⧼parentheses⧽ ⧼parentheses⧽
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.
Inhaltsverzeichnis
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
anstattnet.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 einemm
. 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 indevplugin
,util
undtvdataservice
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
oderprotected
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.
Kategorie⧼colon-separator⧽