Computerorientierte Mathematik

Programmierregeln

Es werden keine Programme abgenommen, die diesen Ansprüchen nicht genügen. Bei theoretischen Hausaufgaben kann das Nicht-Einhalten dieser Regeln zu Punktabzug führen.

Die Programme sind ausführlich auf Englisch kommentiert.

Variablen müssen sinnvolle Namen haben. Nicht erlaubt ist das Durchbuchstabieren der Variablen von a an! Dadurch wird für uns und euch das Verstehen des Programms enorm erleichtert.

Alle nichttrivialen Variablen müssen dokumentiert werden. Dies hat bei ihrer Deklaration zu erfolgen, da dies der einzige Punkte ist, den alle Variablen durchlaufen müssen, bei Übergabeparametern also im Methodenkopf. Und wenn eine Variable nicht einer allgemein gültigen Regel gehorcht, sondern ausgewählte Werte eine ganz bestimmte Information codieren, dann sind alle solchen Werte zu erläutern.

Alle nichttrivialen Code-Fragmente müssen dokumentiert werden. Das gilt insbesondere für nicht triviale Abbruchbedingungen von Schleifen, wichtige Rechenschritte etc.

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.

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.

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.

Variablen dürfen nur im kleinstmöglichen Scope deklariert 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. Nur durch Parameterübergabe kann nämlich halbwegs transparent werden, welche Informationen eine Methode für ihre Ausführung zwingend benötigt.

Fehleingaben des Benutzers werden abgefangen und gemeldet. Es darf dabei keinerlei Fehlermeldung auf der Console (d.h. im xterm) erscheinen.

Die Verwendung von Exceptions soll sich wirklich auf Ausnahmesituationen beschränken. Im Normalfall sollen eure Methoden durch return verlassen werden. Dass ein Stack leer ist, stellt insbesondere keine Ausnahmesituation dar, nicht zuletzt weil dies zuvor ganz legal abgefragt werden kann... Wenn euch jedoch von Dritten unbrauchbare Daten übergeben werden, beispielsweise durch Benutzereingaben, dann dürft ihr sehr wohl mit einer Exception reagieren.

try-catch-Blöcke sind kurz zu halten. Macht euch Gedanken darüber, in welchen Codezeilen überhaupt welche Exceptions auftreten können. Nichttriviale Methoden, bei denen sämtliche Anweisungen in einem einzigen riesigen try-catch-Block liegen, sind somit ausdrücklich verboten.

Die Programme sind ausführlich kommentiert. Insbesondere ist jede Methode und Klasse (außer init() des Applets) nach dem unten stehenden Standard kommentiert.

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.