Codestil

Codestil
Erläuterung und
Definition eines
einheitlichen Codestils
Anfänger-Praktikum SS 2004
Gruppe 2 – Tutor Aaron Ruß
Autor: Tomas Cernaj
Themenvorschau
●
Was versteht man unter einem Codestil?
●
Wozu wird ein Codestil benötigt?
●
Beispiele
●
Definition eines Codestils für unser Projekt
Was ist ein Codestil?
●
englisch: Coding Style
●
einheitliche Richtlinien zur Benennung von
●
–
Klassen
–
Methoden / Funktionen
–
Variablen
Formatierung des Quellcodes, z.B.
–
Einrückungen, Leerzeichen
–
Klammerebenen
Vorteile eines Codestils
●
einheitliche Richtlinien verbessern die
–
Übersichtlichkeit
–
Lesbarkeit
–
Verständlichkeit des Codes
●
schnelleres Erfassen von Sinneinheiten
●
dadurch bessere Wartbarkeit durch andere
Programmierer
Schlechtes Beispiel
import javax.swing.*;
import java.awt.*;
import java.awt.event.*;
public class BadExample{
private static String p="Number of button clicks: ";
private int n=0;
public Component x(){
final JLabel l= new JLabel(p+"0
");
JButton b= new JButton("I'm a Swing button!");
b.setMnemonic(KeyEvent.VK_I);
b.addActionListener(new ActionListener() {public void actionPerformed(ActionEv
l.setLabelFor(b);
JPanel p=new JPanel();
p.setBorder(BorderFactory.createEmptyBorder(30,30,10,30));
p.setLayout(new GridLayout(0,1));
p.add(b);p.add(l);
return p;
}
Modifiziertes Beispiel aus The Java™ Tutorial, © 1995-2002 Sun Microsystems Inc.
1/2
Schlechtes Beispiel
public static void main(String[] args){
JFrame f= new JFrame("SwingApplication");
BadExample a=new BadExample();
Component c=a.x();
f.getContentPane().add(c,BorderLayout.CENTER);
f.addWindowListener(new WindowAdapter(){public void windowClosing(WindowEvent
f.pack();f.setVisible(true);
}}
Modifiziertes Beispiel aus The Java™ Tutorial, © 1995-2002 Sun Microsystems Inc.
2/2
Etablierte Codestile
Gibt es einen allgemein akzeptierten Codestil?
●
üblicherweise von Projekt zu Projekt
verschieden
●
abhängig von der Programmiersprache
●
Java Code Conventions
http://java.sun.com/docs/codeconv/
Java Code Conventions
●
wurden von den Entwicklern der JavaProgrammiersprache benutzt
●
wird von der Firma Sun für die JavaBibliotheken eingesetzt
●
sind an Besonderheiten der Sprache Java
angepasst
Codestil
Erläuterungen zum
verwendeten Codestil
(Java Code Conventions)
Quelldateien-Aufbau
●
Einleitender Kommentar:
/*
* Klassenname
* Versionsinformation
* Datum
*
* Copyright-Hinweis
*/
●
Package- und Import-Anweisungen
●
Klassendeklarationen
●
Dateien sollten nicht zu groß sein (nicht mehr
als 2000 Zeilen)
Klassendeklarationen – Aufbau
1.Klassen-/Interface-Dokumentation (javadoc)
2. class bzw. interface
3.Variablen:
1.public (möglichst vermeiden)
2.protected
3.private
4.Methoden, nach Sinneinheiten gruppiert
Methoden
●
Methoden möglichst kompakt halten
●
sollten auf eine Funktion spezialisiert sein
●
die maximale Länge einer Methode ist
umgekehrt proportional zu ihrer Komplexität
(Linus Torvalds)
Einrückungen
●
Zeilenlänge maximal 80 Zeichen!
●
Ebenen jeweils mit 4 Leerzeichen einrücken:
int doSomething(int i) {
if (i < 0) {
i = 0;
}
return 2 * i;
}
Zeilenumbruch
●
●
●
●
hinter einem Komma
vor einem Operator
nächste Zeile am Beginn des Ausdrucks
ausrichten, falls lesbar
anderenfalls 8 Zeichen einrücken
tueIrgendwas(argument1, argument2, argument3,
argument4);
langerName = beliebigerWert * (irgendeinWert
+ andererWert);
diesIstEinExtremLangerNameFuerEineMethode(eins,
zweitesArgument, drei);
Anweisungen
●
if-Anweisung:
if (bedingung) {
anweisungen;
} else if (bedingung) {
anweisungen;
} else {
anweisungen;
}
●
for-Anweisung:
for (initialisierung; bedingung; update) {
anweisungen;
}
Anweisungen
●
switch-Abfragen:
switch (bedingung) {
case ABC:
anweisungen;
break;
case DEF:
anweisungen;
/* fall through */
case XYZ:
anweisungen;
break;
default:
anweisungen;
break;
}
Zwischenräume
●
Leerzeilen zur Gliederung benutzen
●
Leerzeichen (Space):
–
–
–
–
●
hinter if, for, while etc.
hinter Kommas in Argumentlisten
vor und hinter binären Operatoren (+,* etc.)
hinter einem Typecast (z.B. (double) i + 3)
kein Leerzeichen hinter Methodennamen
Kommentare
●
●
●
●
sollen Informationen liefern, die nicht direkt
aus dem Code abgeleitet werden können
sagen, was der Code macht, aber nicht wie
generell zu jeder Methode eine javadocDokumentation angeben
keine überflüssigen Kommentare!
Kommentare
●
●
Falls ein Codestück funktioniert, aber noch
überarbeitet werden muss, mit /* XXX */
markieren
Erlaubt es, später per Suchfunktion die
Stellen zu finden, die noch Detailarbeit
benötigen
void printList(LinkedList strings) {
/* XXX: Iteratoren verwenden, da effizienter! */
for (int i = 0; i < strings.size(); i++) {
System.out.println(strings.get(i));
}
}
Kommentare
●
Falls ein Codestück einen Fehler enthält, der
noch nicht korrigiert wurde, mit /* FIXME */
markieren:
/* FIXME: das funktioniert nur unter Windows. */
File file = new File("C:\TEMP\README.TXT");
Namensgebung
●
Interfaces und Klassen:
–
–
–
●
ganze Wörter verwenden
jedes Wort mit Großbuchstaben beginnen
Beispiel: PlaylistEntry, ListIterator
Methoden:
–
–
–
Verben, die angeben was die Methode macht
erster Buchstabe klein, sonst jedes Teilwort groß
Beispiel: clear(), sortByName()
javadoc
●
Tool zum automatischen Erstellen von
Dokumentationen aus Quelldateien
●
Spezielle Form von Kommentaren: /**...*/
●
Strukturierung mit Hilfe von speziellen Tags
●
Erzeugt für jede Klasse eine HTML-Seite, in
der alle Methoden aufgeführt, verlinkt und
dokumentiert sind
javadoc
●
Es gibt javadoc-Kommentare für Pakete,
Klassen und einzelne Methoden (je nach
Position des Kommentarblocks)
●
Erzeugt Dokumentation im Stil der JavaKlassenreferenz
javadoc-Beispiel
/**
* Dies ist eine einfache Klasse für zweidimensionale Vektoren.
* @see Vektor#add
*/
public class Vektor {
double x, y;
/**
* Berechnet den <i>Betrag</i> des Vektors.
* @param w Ein Vektor, der zu diesem Vektor addiert werden soll.
* @return
Ein neuer Vektor, der die Summe darstellt.
*/
public Vektor add(Vektor w) {
Vektor v = new Vektor();
v.x = w.x;
v.y = w.y;
return w;
}
}
Wichtige javadoc-Tags
●
@param name desc
Fügt eine Beschreibung des Parameters name hinzu.
●
@return desc
Fügt eine Beschreibung des Rückgabewertes hinzu.
●
{@link package.class#member desc}
Fügt an der aktuellen Position einen Link auf das
angegebene Ziel in den Fließtext ein.
●
@see text
Fügt einen Text zum Absatz der Querverweise hinzu.
●
@see package.class#member desc
Fügt einen Link zu den Querverweisen hinzu.
Namensgebung
●
Variablen:
–
–
–
–
–
●
kurz und prägnant, aber aussagekräftig
erster Buchstabe klein, weitere Wörter groß
Beispiel: int numClients
lokale, temporäre Variablen können einfacher sein
Beispiel: for (int i = 0; i < 10; i++) ...
Konstanten:
–
–
–
Großbuchstaben
Wörter mit Unterstrich getrennt
Beispiel: static final int MAX_WIDTH = 640;
Programmier-Praktiken
●
●
Auf Variablen einer Klasse nur mit Getterbzw. Setter-Funktionen zugreifen
Ermöglicht Kontrolle der übergebenen Werte
class foo {
int bar;
int getBar() {
return bar;
}
void setBar(int value) throws IllegalArgumentException {
if (value < 0) {
throw new IllegalArgumentException();
}
bar = value;
}
}
Gutes Beispiel
/*
* JavaStyle
*
* Based upon example file SwingApplication.java
* taken from The Java(TM) Tutorial
* (c) 1995-2002 Sun Microsystems Inc.
*/
import javax.swing.*;
import java.awt.*;
import java.awt.event.*;
/**
* Diese Klasse öffnet ein Swing-Fenster mit einem Button.
*/
public class JavaStyle {
private static String labelPrefix = "Number of button clicks: ";
private int numClicks = 0;
Modifiziertes Beispiel aus The Java™ Tutorial, © 1995-2002 Sun Microsystems Inc.
1/3
Gutes Beispiel
/*
* Diese Funktion baut das Fenster auf.
*
* @return Ein Component-Objekt des darzustellenden Fensters.
*/
public Component createComponents() {
final JLabel label = new JLabel(labelPrefix + "0
");
JButton button = new JButton("I'm a Swing button!");
button.setMnemonic(KeyEvent.VK_I);
button.addActionListener(new ActionListener() {
public void actionPerformed(ActionEvent e) {
numClicks++;
label.setText(labelPrefix + numClicks);
}
});
label.setLabelFor(button);
JPanel pane = new JPanel();
pane.setBorder(BorderFactory.createEmptyBorder(30, 30, 10,30);
pane.setLayout(new GridLayout(0, 1));
Modifiziertes Beispiel aus The Java™ Tutorial, © 1995-2002 Sun Microsystems Inc.
2/3
Gutes Beispiel
pane.add(button);
pane.add(label);
return pane;
}
public static void main(String[] args) {
JFrame frame = new JFrame("SwingApplication");
JavaStyle app = new JavaStyle();
Component contents = app.createComponents();
frame.getContentPane().add(contents, BorderLayout.CENTER);
frame.addWindowListener(new WindowAdapter() {
public void windowClosing(WindowEvent e) {
System.exit(0);
}
});
frame.pack();
frame.setVisible(true);
}
}
Modifiziertes Beispiel aus The Java™ Tutorial, © 1995-2002 Sun Microsystems Inc.
3/3
Zusammenfassung
●
●
Ein gemeinsamer Codestil soll helfen, wenn
mehrere Programmierer an einem größeren
Projekt arbeiten
Die aufgestellten Regeln sind nicht
hundertprozentig bindend, fassen aber
Erfahrungen aus großen Projekten
zusammen