Technische Universität München Fakultät für Informatik Prof. Dr. Helmut Seidl Michael Petter Melanie Dietz Raphael Geissler Programmierpraktikum Java Entdecken Merkblatt 2 SS 2005 1 Einleitung 1.1 Was sind Code Conventions Java 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 Bytecode- Dateien 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 Javadoc-Kommentar Klassen- oder Interfaceanweisung Kommentar Klassenvariablen Instanzvariablen Konstruktoren Operationen Beschreibung 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 einzeilig Zur Beschreibung von Dateien, Operationen, Datenstrukturen, Algorithmen. Stehen hauptsächlich am Beginn einer Datei oder vor Operationen. kurzer Kommentar, der eine Zeile nicht überschreitet. Voher immer Leerzeile. /* * block comment * almost at the beginning * of classes, methods, etc. if (condition){ /* Handle condition Zeilenende Kann wie einzeiliger Kommentar genutzt werden, aber auch direkt in Zeile des Quelltextes. 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 --; arg ++; arg --; // correct // correct // incorrect Return Rückgabewerte sollten keine Klammern enthalten, ausser es wird dadurch lesbarer. If-else Nie ohne geschweifte Klammern. if ( cond1 ) { else if ( cond2 ) { else { 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: /* falls through case DEF: break; default: 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 CamelCase 3, 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