Programmierstil

Ziel der Übung ist es nicht, irgendwie die geforderte Aufgabenstellung lauffähig zu bekommen. Ziel ist es, einen sauberen, strukturieren und gut lesbaren Quellcode zu produzieren. Dazu sind insb. folgende Punkte zu beachten:

Benennung

Schon an der Art der Bezeichnung sollte erkennbar sein, ob es sich um eine lokale oder globale Variable, eine Konstante oder eine Routine handelt. So kann man beim Programmieren direkt erkennen, ob z.B. eine Zuweisung überhaupt möglich ist bzw. wie weit sich eine Änderung des Wertes im Programm auswirkt. Wir empfehlen Euch folgendes Schema (Ihr dürft aber auch gerne ein anderes benutzen, solange die folgenden Punkte in ähnlicher Weise und einheitlich erfüllt werden):

• Schreibt lokale Variablen vorne klein (center, input), globale Variablen vorne groß (Entry, Point), Konstanten komplett groß (MAX_LENGTH, START_VALUE), Typen vorne mit einem T (TEntry, TPoint) und Routinen - da sie etwas "tun" - am Anfang mit einem Verb (getValue, removeElement).
• Nutzt Binnenmajuskeln (Großbuchstaben im Wortinnern), um die Lesbarkeit zu erhöhen. Verwendet für jedes untergeordnete Wort im Namen einen Großbuchstaben, ebenso bei Buchstaben, die Teil einer Abkürzung sind. Alle anderen Zeichen in dem Namen sind Kleinbuchstaben. Verwendet keine Unterstriche, um Wörter zu trennen (mit Ausnahme von Konstanten).
• Benennt entweder englisch oder deutsch (nicht denglisch).
  Wir empfehlen, sich englische Benennungen anzugewöhnen, da dies im Berufsleben später fast immer gefordert wird. Nutzt dafür hilfreiche Übersetzungsseiten wie dict.leo.org oder www.dict.cc.
• Der Name sollte den Zweck der Variable vermitteln. Der Name sollte so gewählt sein, daß kein Kommentar erforderlich ist.
• Die Länge der Namen ist ungefähr proportional zu ihrem Sichtbarkeitsbereich zu wählen.
  Eine Variable "i" ist höchstens für eine Integer-Laufvariable innerhalb einer zwei- bis dreizeiligen Funktion bzw. Prozedur erlaubt. Besser wäre hier z.B. der Name "row", falls alle Zeilen durchgearbeitet werden. Globale Variablen dürfen auf keinen Fall nur aus einem Buchstaben bestehen.
• Schlüsselwörter wie begin, end, while ... werden entweder alle groß oder alle klein geschrieben, bitte kein wildes Durcheinander!
• Sprechende Namen sind vor allem auch bei den Übergabeparametern von Funktionen/Prozeduren extrem wichtig, da der Funktionskopf theoretisch allein als Erklärung für die Funktionalität ausreichen sollte.
  Sprechende Parameternamen ersetzen natürlich keine Inlinedokumentation!

Einrückung

Euer Programmcode muß vernünftig eingerückt sein. Für jede logische Ebene ist dabei eine weitere Einrücktiefe vorzusehen. Dazu ein Beispiel:

program indent;
begin
  if (...) then
  begin
    repeat
      writeln('Hallo ');
    until ...;

    writeln('Welt');
  end;
end.

Kommentierung

Zu jedem Programm gehört zwingend ein Programmkopf. Dieser enthält:

• Beschreibung des Programms. Wozu ist das Programm da? Welchen Zweck erfüllen die Bestandteile. Die Beschreibungen erfolgen in Umgangssprache.
• Name des Autors / der Autoren
• Datum der Erstellung
• Liste mit wesentlichen Änderungen (mit Datum und Autor). Detailänderungen gehören in die Funktionsköpfe.

Zu jeder Prozedur/Funktion gehört ein Modulkopf. Dieser enthält:

• Beschreibung der Funktion (was macht die Funktion/Prozedur). Der Schwerpunkt liegt hier auf dem WAS und nicht auf dem WIE.
• Auflistung und Beschreibung der Parameter (inhaltlich, nicht durch Nennung ihrer Typen!). Bei Referenzparametern ist zusätzlich zu vermerken, ob die Funktion/Prozedur den Parameter verändert und wenn ja, was dieser Wert bedeutet.
• Bei Funktionen ist der Rückgabewert zu beschreiben.
• Sollte die Funktion Vorbedingungen besitzen, so werden diese erwähnt. Darunter fallen z.B. eingeschränkte Wertebereiche.
• Sollte die Funktion Nachbedingungen haben, so werden diese erwähnt. Darunter fallen insbesondere veränderte Zustände im Programm.
• Innerhalb der Prozeduren/Funktionen ist darauf zu achten, daß die Kommentare dem inhaltlichen Verständnis der Programmlogik dienen. Sie sollen nicht die Grundlagen der Programmiersprache beschreiben!
• Lange Prozeduren sind detaillierter zu dokumentieren als kurze. Da mehrere kurze Prozeduren fast immer ein Problem besser abstrahieren als eine lange Prozedur, kann man an der Prozedurnamensgebung schon häufig viel ablesen, was den Dokumentationsaufwand verringert (Bezeichnernamen sind auch Dokumentation). Außerdem braucht man sich zum Verständnis der Prozedur weniger Information gleichzeitig zu merken.

Ansonsten ist Programmcode so zu kommentieren, daß jemand, der die Sprache beherrscht, aber das Programm nicht kennt, mit dem Kommentar in der Lage ist, den Code zu verstehen.

Sonstiges

Globale Variablen sollten möglichst vermieden werden, da sie eine gute Modularisierung und saubere Schnittstellenbenutzung zunichtemachen. In der PS1-Übung sind sie gänzlich verboten - es sei denn, eine Aufgabenstellung erlaubt sie explizit.

Konstanten sind einzusetzen, wo immer es geht. Macht Euch z.B. bei jeder Zahl, die Ihr direkt in den Code schreibt, Gedanken, ob diese nicht besser durch eine Konstante ersetzt werden könnte!

Goto, Exit, Break, Halt, Terminate und Abort dürfen in den Übungen nicht verwendet werden, da sie zu einer unstrukturierten Programmierung verleiten.

Objektorientierte Lösungen sind in der PS1-Übung nicht zulässig.

Die Größe von Funktionen sollte ein gewisses Maß nicht überschreiten. Man sollte Unterfunktionen dazu benutzen, dieses Ziel zu erreichen. Als Richtlinie gilt: nicht mehr als 20-30 Zeilen pro Prozedur/Funktion. Divide and conquer!