Wie schreibe ich ein verständliches Programm?

Ihre Programme werden einerseits nach Funktionalität und andererseits nach Verständlichkeit bewertet. Funktionalität ist einfach zu prüfen - das Programm erfüllt die Aufgabenstellung oder nicht. Aber wie steht es mit der Verständlichkeit?

Für die Bewertung Ihrer Programme benutzen wir die folgenden Fragen, die Sie sich auch selbst stellen können.

• Sind die Komponenten und Verfahren gut dokumentiert?
• Wird die Programm-Struktur durch konsistente Einrückung und Leerzeilen verdeutlicht?
• Wird das Verfolgen des Programm-Ablaufs durch kleine, wohlstrukturierte Prozeduren unterstützt?
• Sind die Bezeichner aussagekräftig und konsistent gewählt?
• Ist jede Komponente (Prozedur, Variable, Typ) so lokal wie möglich gewählt?
• Kann das Programm ohne großen Aufwand an veränderte Randbedingungen (z.B. durch Ändern von Konstanten) angepaßt werden?

Diese Fragen können mit Hilfe der »Code Conventions for the Java^TM Programming Language« (lokale Kopie) zum Teil beantwortet werden. Diese Richtlinien legen wir Ihnen dringend ans Herz.

Außerdem können Sie »Java Programming Style Guidelines« zu Rate ziehen.

Zusätzlich sollten Sie die folgenden Hinweise beachten:

Sind die Komponenten und Verfahren gut dokumentiert?

• Der Zweck jeder Klasse, jeder Methode und jeder Variable. Beispiel:

  public static int nUsers = 100;  // Maximum number of users
  
  // Return the greatest common divisor of `x' and `y'
  public static void gcd(int x, int y);
  

• Der Zweck von komplizierten Programm-Abschnitten (z.B. Erläuterung eines Algorithmus). Beispiel:

  // `foo' must be recomputed because the base configuration changed
  foo = ...
  

• Alle begründeten Abweichungen von den hier aufgeführten Regeln.

• Sie sollten Sie stets Klarheit und Verständlichkeit im Programm erstreben, statt undurchsichtigen Programmcode durch Kommentieren zu flicken. Schreiben Sie also:

  public static final int CHARACTERS_PER_LINE = 80;

  statt

  public static final int CPL = 80;  // Characters per line

• Ebenfalls sollten Sie keine Dinge kommentieren, die offensichtlich im Programmtext stehen. Schreiben Sie nicht:

  public int i;  // Loop index of type INTEGER

  sondern:

  public int i;  // Loop index

  und auch nicht:

  i = i + 1  // increase `i' by 1 *)

  sondern:

  i = i + 1

Kommentare sollten entweder

• in einer eigenen Zeile vor dem beschriebenen Gegenstand stehen oder
• auf derselben Zeile nach dem beschriebenen Gegenstand stehen.

Wird die Programm-Struktur durch konsistente Einrückung und Leerzeilen verdeutlicht?

• Jeder Befehl kommt in eine neue Zeile.
• Strukturen sollten in mehrere Zeilen formatiert werden:

  if Bedingung {
      1. Zweig
  } else {
      2. Zweig
  }
  

  und

  for/while Bedingung {
      ...
  }
  

• Vor und nach jedem Block, jedem if-then-else und jeder Schleife (for, while) soll eine Zeile freigelassen werden.
• Bei Schachtelungen muß eingerückt werden - 4 Zeichen sind das Optimum.
• Verwenden Sie stets die voreingestellte Tabulatorbreite von 8 Zeichen.
• Eine Zeile sollte nicht länger als 79 Zeichen sein.
• Lassen Sie Leerzeichen
  • um Operatoren und Zuweisungen: a = 1 + (2 * 3) oder if (a == 0) and (b == 1)
  • nach Satzzeichen: x = f(a, b, c)
  Um Klammern (()[]{}) und Punkte (.) müssen Sie keine Leerzeichen lassen.

Wenn Sie als Editor den XEmacs nutzen, erhalten Sie Unterstützung beim Einrücken wenn Sie TAB drücken.

Wird das Verfolgen des Programm-Ablaufs durch kleine, wohlstrukturierte Prozeduren unterstützt?

• Algorithmen
• Prozeduren, die eine Funktion aus der Aufgabenstellung realisieren
• Elementare Operationen auf Datenstrukturen

Sind die Bezeichner aussagekräftig und konsistent gewählt?

• Die Namen von Prozeduren oder von Variablen sollen eindeutig und selbsterklärend sein. Aus jedem Namen sollte der Zweck ohne weiteres Nachschlagen ersichtlich sein.
  Beispiel: Schreiben Sie

  greatestCommonDivisor

  statt

  f27

• Namen mit einem einzigen Buchstaben wie i oder j dürfen nur als Laufindizes von Schleifen sowie als Parameter einfacher mathematischer Funktionen verwendet werden.
  Beispiel: Schreiben Sie

  linesPerPage

  statt

  n

• Verwenden Sie keine nichtssagenden Namen wie help, dummyn temp, result oder test.
  Beispiel: Schreiben Sie

  terminateProgram

  statt

  flag

• Kodieren Sie keine weitere Information (wie z.B. den Typ oder den Modulnamen) in den Namen.
  Beispiel: Schreiben Sie

  public int numberOfUsers

  statt

  public int iNumberOfUsers

  und

  public int lines[] = new int[MAX]

  statt

  public int iaMAXlines = new int[MAX]

• Benutzen Sie Groß/Kleinschreibung (und Unterstriche), um Wortteile zu trennen.
  Beispiel: Schreiben Sie

  workingDaysPerYear

  statt

  workingdaysperyear

• Benutzen Sie eine einheitliche Groß/Kleinschreibung für Schlüsselwörter, Module, Konstanten, Variablen, Prozeduren und Verbundelemente.
  Beispiel:
  • String - Klasse, beginnend mit Großbuchstaben
  • MAX_SIZE - Konstante, durchgehend groß und mit Unterstrich getrennt
  • arraySize - Variable, beginnend mit Kleinbuchstaben
  • printName - Methode, beginnend mit Kleinbuchstaben

• Verwenden Sie englischsprachige Namen.

Ist jede Komponente (Prozedur, Variable, Typ) so lokal wie möglich gewählt?

Wenn eine Komponente nicht benutzt wird, hat sie in Ihrem Programm nichts verloren.

Kann das Programm ohne großen Aufwand an veränderte Randbedingungen (z.B. durch Ändern von Konstanten) angepaßt werden?

Dies gilt besonders für numerische Konstanten. In Ihrem Programm sollten keine numerischen Literale außer 0 und 1 vorkommen (ein Literal ist ein Wert, der für sich selbst steht - z.B. 500 oder 3.14). Verwenden Sie stets Konstanten (z.B. numberOfUsers oder Pi), damit das Programm an nur einer Stelle geändert werden muß. Warning: include(footer.php3): failed to open stream: No such file or directory in /data/www/htdocs/infosun/st/edu/prog2-06/style.php3 on line 297 Warning: include(): Failed opening 'footer.php3' for inclusion (include_path='.:/usr/share/php:/usr/share/pear') in /data/www/htdocs/infosun/st/edu/prog2-06/style.php3 on line 297