Java Entdecken Merkblatt 2 - Technische Universität München

Technische Universität München
Fakultät für Informatik
Prof. Dr. Helmut Seidl
Michael Petter
Melanie Dietz
Raphael Geissler
SS 2005
Programmierpraktikum Java Entdecken
Merkblatt 2
Java Code Conventions
1 Einleitung
1.1 Was sind Code Conventions
Code Conventions sind Vereinbarungen unter Softwareentwicklern um das Layout des Quelltextes einheitlich zu halten. Dies bezieht sich vorallem auf Formatierungen, aber auch auf Struktur,
Namesgebung, etc.
1.2 Warum Code Conventions
Ein Großteil der Zeit für die Entwicklung von Computerprogrammen wird unnötigt durch Pflege
des Quellcodes verbraucht. Da zudem an fast keinem Projekt nur eine Person arbeitet, die zudem
kaum ihren Stil beibehält, empfiehlt es sich vorher Regeln für das Layout zu erarbeiten. Diese
verbessern die Lesbarkeit des Codes erheblich.
Im Anschluss werden nur die wichtigsten Konventionen erläutert, für detailliertere Informationen sei auf die Conventions von Sun 1 hingewiesen.
2 Dateinnamen
Bei den Dateinamen sei nur kurz erwähnt, dass Java Quelltext-Dateien auf .java und BytecodeDateien auf .class enden.
3 Dateiorganisation
Grundsätzlich ist es zu vermeiden, dass Dateien mehr als 2000 Zeilen Quellcode enthalten. Ausserdem werden public und protected Klassen jeweils in eigene Dateien verfasst.
1 http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
1
3.1 Struktur der Quelltext-Datei
Ganz allgemein besitzt eine Code-Datei folgenden Aufbau:
1. Dateikommentar
2. Package- und Importanweisungen
3. Klassen- und Interfacestruktur
3.2 Package- und Importanweisungen
Nach dem Kommentar am Beginn einer Quelldatei, der vorallem Klasseninformationen enthält,
steht zuerst die Packageanweisung, gefolgt von den Importanweisungen, die alle explizit angegeben werden. D.h. in der Importanweisung ist kein Platzhalter erlaubt. Falls z.B. die Klasse
java.util.Vector eingebunden werden soll, so schreibt man import java.util.Vector und nicht import java.util.*. So wird sofort klar welche Klassen in dieser Datei benutzt werden.
3.3 Klassen- und Interfacedeklarationen
Deklarationsteil
Beschreibung
Javadoc-Kommentar
Klassen- oder Interfaceanweisung
Kommentar
Klassenvariablen
Instanzvariablen
Konstruktoren
Operationen
siehe Javadoc
für Quelltext relevanter Kommentar
in Reihenfolge public, protected, private
in Reihenfolge public, protected, private
Lesbarkeit entscheidend
Tabelle 1: Klassen- und Interfacedeklarationen
4 Einrückung
Grundsätzlich werden keine Tabs, sondern Leerzeichen verwendet. Allgemein werden vier Leerzeichen zum Einrücken benutzt. Zeilen, die länger als 80 Zeichen sind, werden umgebrochen.
Falls ein Ausdruck nicht in eine Zeile passt, wird nach folgenden Regeln umgebrochen:
• nach einem Komma
• vor einem Operator
• ausrichten der neuen Zeile am Anfang des Ausdrucks
• falls, die obigen Regeln zu schlecht lesbarem Code führen, wird stattdessen jede neue
Zeile um acht Leerzeichen eingerückt
2
irgendeineOperation(langerAusdruck1, langerAusdruck2, langerAusdruck3,
langerAusdruck4, langerAusdruck5);
variable = irgendeineOperation1(langerAusdruck1,
irgendeineOperation2(langerAusdruck2,
langerAusdruck3));
variable = langeVariable1 * (langeVariable2 + langeVariable3 - langeVariable4)
+ 10 * langeVariable5;
Abbildung 1: Einrückbeispiele
5 Kommentar
Bei den Kommentaren werden generell zwei Arten unterschieden. Dem Implementationskommentar, der in erster Linie spezielle Implementationen dokumentiert und dem Dokumentationskommentar, der Klassen, Interfaces und Operationen beschreibt. Aus diesem wird dann eine
HTML-Dokumentation generiert.
5.1 Implementationskommentar
Es existieren vier Arten von Implementationskommentaren, die wichtigeren drei werden in Tabelle 2 dargestellt.
5.2 Dokumentationskommentar
Wie schon oben erwähnt, steht der Dokumentationskommentar vor den Klassen, Interfaces und
Operationen, die er beschreibt. Kenntlich wird dieser durch die Zeichen /** ... */ gemacht (siehe
Abb. 2). Für die Dokumentation benötigt man einige tags, die beim Generieren dann ausgewertet
/**
* class description
*/
Abbildung 2: Javadoc Klassenbeschreibung
werden. Im Anschluss werden nur die Wichtigsten aufgeführt, für Details sei auf “How to Write
Doc Comments for Javadoc” 2 verwiesen.
• Jeder Javadoc-Kommentar beginnt mit einer informellen Beschreibung. Diese wird durch
einen “.” abgeschlossen. Kann aber auch aus mehreren Sätzen bestehen.
2 http://java.sun.com/products/jdk/javadoc/writingdoccomments.html
3
Bezeichnung
Erklärung
Beispiel
Block
Zur Beschreibung von Dateien, Operationen, Datenstrukturen, Algorithmen. Stehen hauptsächlich am Beginn einer Datei oder vor Operationen.
/*
* block comment
* almost at the beginning
* of classes, methods, etc.
*/
einzeilig
kurzer Kommentar, der eine Zeile nicht überschreitet. Voher immer
Leerzeile.
if (condition){
Zeilenende
Kann wie einzeiliger Kommentar genutzt werden, aber auch direkt in
Zeile des Quelltextes.
/* Handle condition */
...
}
if (condition){
// first alternative
...
}else{
return true; // second
}
Tabelle 2: Implementationskommentare
• @param - falls eine Operation Parameter enthält, wird jede durch ein einzelnes @param
beschrieben. Dem Parameternamen folgt in der nächsten Zeile dessen Beschreibung.
• @return - analog zu @param beschreibt @return den Rückgabewert.
• @see - analog zu @param gibt @see Verweise zu anderen Klassen, Interfaces oder Operationen an.
• @overrides - testet, ob eine Funktion tatsächlich die Funktion der Oberklasse überschreibt.
/**
* The Vector class implements
* a growable array of objects.
* ...
* @see List
* @author Max Mustermann
*/
public class Vector {
...
/**
* @param initialCapacity
*
the initial capacity.
*/
public Vector (int initialCapacity ){
...
}
4
/**
* @return
*
Number of components.
*/
public int size (){
...
}
}
6 Deklarationen
Folgende Regeln sind bei Deklarationen zu beachten:
• Am besten jede Deklaration in eine Zeile, auch falls diese vom gleichen Typ sind. So kann
jede Deklaration leicht mit einem Kommentar versehen werden.
• Auf keinen Fall Variablendeklarationen, Arraydeklarationen, etc. mischen.
• Falls möglich alle Deklarationen gleich initialisieren.
• In Blöcken stehen Deklarationen immer am Beginn. Einzige Ausnahme for-Schleifen.
• Eine öffnende geschweifte Klammer kommt nie in eine neue Zeile.
• Eine schließende geschweifte Klammer bekommt immer einer neue Zeile, ausser der
Block ist leer, dann steht sie direkt hinter der öffnenden.
• Bei Operationen steht die öffnende Runde Klammer direkt im Anschluss an den Operationsnamen. Im Gegensatz zu Anweisung (while, if, for, etc.).
class Sample {
int m_variable1 ; // first variable
int m_variable2 ; // second variable
int m_variable3 , m_array1 []; //WRONG
Sample (int variable1 , int variable2 ) {
m_variable1 = variable1 ;
m_variable2 = variable2 ;
}
int emptyOperation () {}
void loopOperation () {
for (int i = 0; i < 10; i ++){
...
}
}
}
5
7 Statements
• Pro Zeile nur ein einfaches Statement.
arg ++;
arg - -;
// correct
// correct
arg ++; arg - -;
// incorrect
• Return Rückgabewerte sollten keine Klammern enthalten, ausser es wird dadurch lesbarer.
• If-else Nie ohne geschweifte Klammern.
if ( cond1 ) {
statements ;
} else if ( cond2 ) {
statements ;
} else {
statements ;
}
• for analog zu if-else.
• while analog zu if-else.
• do-while analog zu if-else.
• switch Immer mit default-Anweisung. Falls eine break-Anweisung ausgelassen wird, Kommentar einfügen.
switch ( cond ) {
case ABC :
statements ;
/* falls through */
case DEF :
statements ;
break;
default:
statements ;
break;
}
8 Leerzeilen
Zwei Leerzeilen zwischen
• Abschnitte einer Quelldatei
6
• Klassen- und Interfacedefintionen
Eine Leerzeile
• zwischen Operationen
• zwischen Variablen und Operationen
• zwischen logischen Abschnitten innerhalb einer Funktion
• vor einem Block- oder einzeiligen Kommentar
9 Namensgebung
• Packages grundsätzlich klein. Getrennt durch Punkte.
• Klassen und Interfaces erster Buchstabe groß und in CamelCase3 , d.h. bei zusammengesetzen Wörtern jeder erste Buchstabe eines Teilwortes groß, z.B. SimpleType.
• Operationen erster Buchstabe klein und CamelCase. Am besten in Verbform.
• Variablen erster Buchstabe klein und wieder CamelCase.
• Konstanten alle Buchstaben groß.
3 http://en.wikipedia.org/wiki/Camelcase
7