Computerorientierte Mathematik II (WS99/00) - Programmierregeln -

Fachbereich Mathematik

P1	Die Programme sind ausführlich kommentiert. Insbesondere ist jede Methode und Klasse (außer init() des Applets) nach dem unten stehenden Standard kommentiert.
P2	Methoden sind kurz und übersichtlich. Als Richtwert gilt: Keine Methode sollte länger als eine Bildschirmseite (70 Zeilen) sein (gerechnet bei einem Befehl pro Zeile und vielen Leerzeilen). Lieber mehr Methoden als zu wenige einsetzen.
P3	Es dürfen keine nichttrivialen Programmsegmente in gleicher oder nur geringfügig veränderter Form mehrmals im gesamten Programm auftauchen. Das anscheinend vielgeliebte fünffache Kopieren des gleichen Codestücks mit anschließenden einfachen Änderungen ist hiermit verboten. Solch Code gehört in eigene Methoden verfrachtet.
P4	Variablen dürfen nur im kleinstmöglichen Scope definiert werden. Instanzvariablen (also solche im Klassenscope), die nur vorübergehend in Methoden benutzt werden, sind nicht erlaubt. Das gleiche gilt für Instanzvariablen, die als bloßer Ersatz für die Parameterübergabe eingesetzt werden.
P5	Variablen, Klasse, Interfaces und Methoden müssen sinnvolle Namen haben. Dadurch wird für uns und Euch das Verstehen des Programms enorm erleichtert.
P6	GroßKleinschreibung verwenden. Verwendet die gemischte GroßKleinschreibung für Namen von Klasse, Interfaces und Methoden (bei Variablen bleibt es Euch überlassen). Namen von Variablen, Interfaces und Klassen beginnen mit einem Großbuchstaben. Methoden beginnen mit einem Kleinbuchstaben, das erste Wort sollte ein Verb sein.
P7	Alle nichttrivialen Variablen müssen dokumentiert werden. Vorbei sind die Zeiten, als manche von Euch einfach die Variablen von a an durchbuchstabierten!
P8	Der Quelltext ist sinnvoll einzurücken. Ansonsten wird das Zuordnen von z. B. Schleifenanfängen und -enden sehr schwierig, worunter erfahrungsgemäß nicht nur derjenige leidet, der das Programm abnehmen soll, sondern auch Ihr selbst.
P9	Fehleingaben des Benutzers werden abgefangen und gemeldet. Es darf dabei keinerlei Fehlermeldung auf der Console (d. h. im xterm) erscheinen.

Dokumentierstandard

Klassen

/**
 * A christmas tree that always nicely fits into its canvas.
 * Can be used just like any other Component.
 */
 public class XmasTree
 {
   ...

Methoden

/**
 * Compute the volume of a cube with the specified dimensions.
 *
 * @param h the height of the cube
 * @param w the width of the cube
 * @param d the depth of the cube
 * 
 * @return the volumen of the cube
 *
 * @exception CubeException if any of the given parameters is negative
 */
public double computeVolume(double h, double w, double d) throws CubeException
{
  ...

Es steht direkt vor der Methode ein mehrzeiliger Kommentar, der wieder mit /** und jede weitere Zeile mit * beginnt.

Anschließend ein oder mehrere Zeilen, die die Methode kurz beschreiben. Hierhin gehören auch alle Voraussetzungen, die vielleicht erfüllt sein müssen, bevor die Methode aufgerufen werden sollte.

Es folgen Zeilen der Form
   @param Variablenname Beschreibung
für jeden Parameter der Methode.

In ähnlicher Weise kommt nun eine Zeile der Form
   @return Beschreibung
die den Rückgabewert erklärt. Bei void-Methoden steht natürlich keine solche Zeile.

Falls die Methode eine Ausnahme auswerfen kann, muß diese auch dokumentiert werden durch die Zeile
   @exception Exceptionname Bedingungserläuterung
die in Worten angibt, wann eine solche Exception erzeugt wird.

Alexander Schwartz Last modified: Tue Apr 11 11:29:55 MET DST 2000