Codestil. Erläuterung und Definition eines einheitlichen Codestils. Anfänger-Praktikum SS 2004 Gruppe 2 Tutor Aaron Ruß Autor: Tomas Cernaj

Transkript

1 Codestil Erläuterung und Definition eines einheitlichen Codestils Anfänger-Praktikum SS 2004 Gruppe 2 Tutor Aaron Ruß Autor: Tomas Cernaj

2 Themenvorschau Was versteht man unter einem Codestil? Wozu wird ein Codestil benötigt? Beispiele Definition eines Codestils für unser Projekt

3 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

4 Vorteile eines Codestils einheitliche Richtlinien verbessern die Übersichtlichkeit Lesbarkeit Verständlichkeit des Codes schnelleres Erfassen von Sinneinheiten dadurch bessere Wartbarkeit durch andere Programmierer

5 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, Sun Microsystems Inc. 1/2

6 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, Sun Microsystems Inc. 2/2

7 Etablierte Codestile Gibt es einen allgemein akzeptierten Codestil? üblicherweise von Projekt zu Projekt verschieden abhängig von der Programmiersprache Java Code Conventions

8 Java Code Conventions wurden von den Entwicklern der Java- Programmiersprache benutzt wird von der Firma Sun für die Java- Bibliotheken eingesetzt sind an Besonderheiten der Sprache Java angepasst

9 Codestil Erläuterungen zum verwendeten Codestil (Java Code Conventions)

10 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)

11 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

12 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)

13 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;

14 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);

15 Anweisungen if-anweisung: if (bedingung) { anweisungen; else if (bedingung) { anweisungen; else { anweisungen; for-anweisung: for (initialisierung; bedingung; update) { anweisungen;

16 Anweisungen switch-abfragen: switch (bedingung) { case ABC: anweisungen; break; case DEF: anweisungen; /* fall through */ case XYZ: anweisungen; break; default: anweisungen; break;

17 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

18 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 javadoc- Dokumentation angeben keine überflüssigen Kommentare!

19 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));

20 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");

21 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()

22 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

23 javadoc Es gibt javadoc-kommentare für Pakete, Klassen und einzelne Methoden (je nach Position des Kommentarblocks) Erzeugt Dokumentation im Stil der Java- Klassenreferenz

24 javadoc-beispiel /** * Dies ist eine einfache Klasse für zweidimensionale Vektoren. Vektor#add */ public class Vektor { double x, y; /** * Berechnet den <i>betrag</i> des Vektors. w Ein Vektor, der zu diesem Vektor addiert werden soll. 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;

25 Wichtige name desc Fügt eine Beschreibung des Parameters name desc Fügt eine Beschreibung des Rückgabewertes hinzu. package.class#member desc Fügt an der aktuellen Position einen Link auf das angegebene Ziel in den Fließtext text Fügt einen Text zum Absatz der Querverweise package.class#member desc Fügt einen Link zu den Querverweisen hinzu.

26 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;

27 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;

28 Gutes Beispiel /* * JavaStyle * * Based upon example file SwingApplication.java * taken from The Java(TM) Tutorial * (c) 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, Sun Microsystems Inc. 1/3

29 Gutes Beispiel /* * Diese Funktion baut das Fenster auf. * 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, Sun Microsystems Inc. 2/3

30 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, Sun Microsystems Inc. 3/3

31 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