Programmierrichtlinien (PDF)

Programmierrichtlinien für Modula-2 RR, 15.10.1999 1
Programmierrichtlinien für
Modula-2
Diese Programmierrichtlinien sind für alle Modula-2-Programme, die im Rahmen des
Programmierkurses entstehen, verbindlich.
Inhaltsverzeichnis
1 Motivation......................................................................................................................... 2
2 Programmkonstrukte ...................................................................................................... 2
2.1 Module......................................................................................................................... 2
2.2 Prozeduren.................................................................................................................. 4
2.3 Variable........................................................................................................................ 4
2.4 Konstanten .................................................................................................................. 4
2.5 Typen ........................................................................................................................... 5
2.6 Verwendung von Modula-2-Konstrukten.............................................................. 5
2.7 Verschachtelung und Länge von Programmteilen ............................................... 6
3 Namenskonventionen..................................................................................................... 7
3.1 Allgemeines................................................................................................................. 7
3.2 Module......................................................................................................................... 8
3.3 Prozeduren.................................................................................................................. 8
3.4 Variablen ..................................................................................................................... 8
3.5 Konstanten .................................................................................................................. 8
3.6 Typen ........................................................................................................................... 8
4 Formatierung .................................................................................................................... 8
4.1 Allgemeines................................................................................................................. 9
4.2 Einrückungen, Abstände, Ausrichtung .................................................................. 9
4.3 Kontrollstrukturen ................................................................................................... 12
4.4 Importe ......................................................................................................................13
4.5 Deklarationen ........................................................................................................... 13
4.6 Prozeduren................................................................................................................ 14
4.7 Module.......................................................................................................................15
5 Kommentierung ............................................................................................................. 15
5.1 Allgemeine Hinweise zur Kommentierung ......................................................... 15
5.2 Kopfkommentare ..................................................................................................... 16
5.3 Eingeschobene Kommentare .................................................................................. 20
5.4 Erläuterungen ........................................................................................................... 21
6 Beispiele .......................................................................................................................... 21
6.1 Hauptmodul HelloWorld.mod .............................................................................. 21
6.2 Definitionsmodul Stacks.def .................................................................................. 22
6.3 Implementierungsmodul Stacks.mod................................................................... 24

Programmierrichtlinien für Modula-2 RR, 15.10.1999 2
1 Einleitung
1.1 Zielsetzung
Ziel dieser Richtlinie ist es, in allen Modula-2-Projekten einen möglichst einheitlichen
und verständlichen Programm-Code zu erhalten. Die Programme sollen von anderen
Entwicklern verstanden, geprüft, gewartet und verändert werden können. Das soll
durch eine einheitliche Darstellung der Programmtexte unterstützt werden.
Den einzelnen Vorgaben liegen folgende grundsätzlichen Überlegungen zugrunde:
• Einfachheit: Die Programme sind verständlich zu formulieren sowie ausreichend
zu kommentieren und zu dokumentieren. Trickreiche Programme, die
nur mit großem Aufwand zu verstehen sind, helfen niemandem!
• Einheitlichkeit: Für alle Belange, für die Richtlinien existieren, sollen diese auch
verwendet werden. Ist ein Punkt nicht klar geregelt, soll im Geiste dieser Richtlinie
verfahren werden.
• Stabilität, Verständlichkeit und Änderbarkeit sind in jedem Fall wichtiger als die
Effizienz eines Programms. Optimierungen zu Lasten der Verständlichkeit sollten
nur dann durchgeführt werden, wenn es nicht anders geht. Dann bedürfen
sie besonders ausführlicher Kommentierung.
• Portabilität: Programme dürfen grundsätzlich keine Besonderheiten von benutzten
Compilern, Betriebssystemen oder zugrundeliegenden Bibliotheken verwenden!
Falls dies einmal nicht zu umgehen ist, so ist das in der Dokumentation
zum Code genau zu erklären.
Eine Programmierrichtlinie ist immer ein Kompromiss zwischen konkurrierenden
Zielen. Je nach dem eingenommenen Blickwinkel scheinen die Richtlinien zu detailliert
und zu einschränkend – oder aber zu nachlässig und zu unpräzise. Man kann
beliebig lange über einzelne Details streiten; im Endeffekt handelt es sich um
Geschmacksfragen, aber de gustibus non est disputandum 1 . Es kommt vor allem darauf
an, überhaupt über Richtlinien zu verfügen. Nur dann kann man in den Genuss
der Vorteile kommen.
1.2 Anwendung
Richtlinien sind keine Dogmen. Sie sollten immer unter Anwendung gesunden Menschenverstands
verwendet werden. Es gibt immer – wenn auch selten – Situationen,
in denen eine buchstabengetreue Befolgung sinnlos oder zumindest fraglich ist. In
einer solchen Situation kann von den Richtlinien abgewichen werden. Die Abweichung
sollte aber immer dokumentiert und begründet werden.
2 Programmkonstrukte
Dieser Abschnitt legt fest, wie einzelne Programmkonstrukte von Modula-2 verwendet
werden sollen. Dabei werden die Möglichkeiten, die Modula-2 bietet, etwas eingeschränkt.
1. lat.: Über Geschmack soll man nicht streiten.

Programmierrichtlinien für Modula-2 RR, 15.10.1999 3
2.1 Module
Grundsätze. Alle Programme sollen in möglichst sinnvolle Module zergliedert werden.
Das Hauptmodul 1 soll nur aus wenigen Zeilen (maximal 20) bestehen und keine
Prozeduren enthalten. 2
Die Bestandteile eines Programms werden nach dem folgenden Schema auf Dateien
verteilt:
• Das Hauptmodul (module) wird in eine eigene Datei geschrieben. Diese Datei
trägt den Namen des Hauptmoduls (und damit des ausführbaren Programms),
gefolgt von der Endung .mod, z.B. HelloWorld.mod.
• Jedes Definitionsmodul (definition module) kommt vollständig in eine eigene
Datei. Diese trägt den Modulnamen und hat die Endung .def, z.B.
Stacks.def.
• Jedes Implementierungsmodul (implementation module) kommt vollständig in
eine eigene Datei. Diese trägt den Modulnamen und hat die Endung .mod, z.B.
Stacks.mod.
Module werden verwendet, um
• zusammengehörige Funktionalitäten zu gruppieren,
• globale Deklarationen zusammenzufassen,
• abstrakte Datentypen und Datenkapseln zu realisieren.
Jedes Modul (mit Ausnahme des Hauptmoduls) besteht aus einem Definitionsmodul
und einem Implementierungsmodul.
Aufbau. Das Definitionsmodul untergliedert sich wie folgt:
1. Importe
2. Definition von Konstanten, die zur Typdefinition notwendig sind
3. Typdefinitionen
4. Konstantendefinitionen
5. Variablendeklarationen
6. Prozedurdeklarationen
Die Schnittstelle, die durch das Definitionsmodul beschrieben wird, soll möglichst
wenige Typen und Operationen haben und möglichst stabil bleiben. In das Definitionsmodul
gehören nur Angaben, die nach außen wirklich sichtbar sein müssen.
Das Implementierungsmodul untergliedert sich in:
1. Importe
2. Definition von Konstanten, die zur Typdefinition notwendig sind
3. Typdefinitionen
1. Hauptmodul ist das Modul, in dessen Rumpf die eigentliche Programmausführung beginnt.
Es steht an der Spitze der Import-Hierarchie.
2. Ausnahme: Programme mit weniger als 100 ausführbaren Programmzeilen dürfen ohne Zergliederung
in kleinere Module entwickelt werden. Das Programm wird in diesem Fall in Prozeduren
gegliedert, die direkt im Hauptmodul untergebracht sind.

Programmierrichtlinien für Modula-2 RR, 15.10.1999 4
4. Konstantendefinitionen
5. Variablendeklarationen
6. Definition interner Prozeduren
7. Definition der Prozeduren des Definitionsmoduls (in der gleichen Reihenfolge
wie im Definitionsmodul)
8. Rumpf
Ein Hauptmodul wird analog zu einem Implementierungsmodul aufgebaut.
2.2 Prozeduren
Grundsätze. Jedes Modul sollte in sinnvolle Prozeduren zergliedert werden. Jede
Prozedur sollte eine klar definierte Aufgabe besitzen und übersichtlich sein. Daher ist
es häufig sinnvoll, Teilfunktionalitäten in weitere Prozeduren auszulagern.
Aufbau. Ebenso wie in Modulen muss auch in Prozeduren die Reihenfolge der einzelnen
Deklarationen eingehalten werden.
1. Konstantendefinitionen
2. Variablendeklarationen
3. Definitionen lokaler Prozeduren
4. Rumpf
Typdefinitionen sollten nicht innerhalb von Prozeduren erfolgen, sondern immer im
Modul. Ebenso sollen Konstanten nur in Ausnahmefällen innerhalb einer Prozedur
definiert werden.
Parameterübergabe. Der Typ eines formalen Parameters muss so restriktiv wie möglich
angegeben werden. Wertparameter sind Referenzparametern (VAR-Parameter)
vorzuziehen.
Seiteneffekte. Funktionsprozeduren sollen nach Möglichkeit keine Seiteneffekte
(Nebenwirkungen, z.B. auf globale Variable) haben.
2.3 Variable
Globale Variable. Globale Variablen sollen nur sehr sparsam verwendet werden. Ihre
Sichtbarkeit soll möglichst stark eingeschränkt sein. Eine Übergabe von Werten an
Prozeduren über globale Variablen ist verboten (stattdessen Parameter verwenden!),
ebenso der Informationsfluss aus Prozeduren heraus über globale Variablen (stattdessen
Rückgabewerte oder VAR-Parameter verwenden!).
Sichtbarkeit. Variablen sollen von Modulen nur dann exportiert werden, wenn es
unbedingt notwendig ist. Besser als eine allgemeine Sichtbarkeit einer globalen Variablen
sind in jedem Fall Zugriffsprozeduren (Grundsatz der Kapselung).
Typ. Der Typ einer Variablen soll möglichst genau an den vorgesehenen Einsatzzweck
angepasst sein. Es sollte zum Beispiel für eine Zählvariable für Werte zwischen 1 und
100 nicht einfach der Typ INTEGER verwendet werden, sondern ein geeigneter
Bereichstyp.

Programmierrichtlinien für Modula-2 RR, 15.10.1999 5
2.4 Konstanten
Anstelle von festen Zahlen (und Zeichenketten) im Programmtext sollen (sofern sinnvoll)
Konstanten verwendet werden. Je nach Bedeutung sind diese
• im Implementierungsmodul (interne Konstanten des jeweiligen Moduls) oder
• im Definitionsmodul (für die Verwendung des Moduls notwendige Konstanten)
definiert.
Die Verwendung von Konstanten erleichtert eine Änderung des Programms, da nur
der Wert der Konstanten verändert werden muss und nicht alle Verwendungen des
Werts. Wird eine Konstante nur innerhalb einer Prozedur benötigt, kann sie auch zu
dieser lokal deklariert werden.
2.5 Typen
Die Typen von Variablen sollen immer explizit erzeugt werden (benannte Typen).
Anonyme Typen, d.h. direkt bei der Deklaration der Variablen definierte Typen, sind
verboten. Beispielsweise soll statt
VAR inputLine: ARRAY[1 .. 256] OF CHAR; (*anonymous type!*)
Folgendes geschrieben werden:
CONST MaxBufferLength = 256;
TYPE Buffer: ARRAY[1 .. MaxBufferLength] OF CHAR;
VAR inputLine: Buffer;
Für Typdefinitionen gilt das oben für Konstanten gesagte: Sie sollen je nach ihrer Verwendung
innerhalb eines Definitionsmoduls, innerhalb eines Implementierungsmoduls
oder innerhalb einer Prozedur definiert werden.
2.6 Verwendung von Modula-2-Konstrukten
2.6.1 Ausdrücke
Ausdrücke sollen so lesbar wie möglich gestaltet werden. Komplexe oder trickreiche
Ausdrücke bedürfen eines Kommentars zur Erklärung. Klammern sollen verwendet
werden, wenn für das Verständnis explizites Wissen über die Auswertungsreihenfolge
nötig ist. 1 Eine deutliche Klammerung ist in jedem Fall einer undurchsichtigen
Abhängigkeit von der Auswertungsreihenfolge vorzuziehen.
Logische Ausdrücke sollen nach Möglichkeit positiv ausgedrückt werden, da Negationen
schlechter verständlich sind. Das beeinflusst bereits die Wahl der Variablen und
deren Aussage. So sollte zum Beispiel anstelle von
besser
IF (NOT fileFound) THEN ...
IF fileMissing THEN ...
verwendet werden. Allerdings sollen für die Einhaltung dieser Regel nicht zusätzliche
Variablen eingeführt werden. Eine Negation ist dann das kleinere Übel.
1. Zum Beispiel ist eine Klammerung für Punkt vor Strich nicht notwendig, logische Operatoren
sollten hingegen geklammert werden.

Programmierrichtlinien für Modula-2 RR, 15.10.1999 6
2.6.2 CASE-Anweisung
Die CASE-Anweisung ist verschachtelten IF-Anweisungen vorzuziehen. Es sollen
keine Bereiche von Aufzählungstypen in CASE-Anweisungen angegeben werden, da
sich bei einer Änderung des Aufzählungstyps dessen Semantik verändert (stattdessen
explizite Aufzählung).
Der Programmierer soll explizit alle Auswahlmöglichkeiten abfragen, also wenn
möglich auf den ELSE-Zweig verzichten. Die Verwendung des ELSE-Zweigs ist allerdings
angebracht, wenn man für alle übrigen Fälle eine Fehlermeldung generieren
möchte oder die CASE-Anweisung dazu dient, zwei oder drei spezielle Werte aus
einem großen Wertebereich herauszufiltern.
2.6.3 Schleifen
FOR-Schleifen sind anderen Schleifen vorzuziehen, da sie immer terminieren. Die
nächstbeste Wahl sind WHILE- und REPEAT-Schleifen. In sehr komplexen Fällen können
LOOP-Schleifen verwendet werden. Dabei ist allerdings darauf zu achten, dass
die Schleife an möglichst wenigen Stellen durch EXIT-Anweisungen verlassen wird.
EXIT-Anweisungen in WHILE- und REPEAT-Schleifen sind nur in Ausnahmefällen
erlaubt.
2.6.4 RETURN-Anweisung
Funktionsprozeduren sollen an möglichst wenigen Stellen (normalerweise nur an
einer einzigen) durch eine RETURN-Anweisung verlassen werden. Falls zu diesem
Zweck allerdings eine zusätzliche Variable eingeführt werden muss, um den Rückgabewert
zu speichern, kann die Regel gebrochen werden. Es wird empfohlen, der Variablen,
die den Rückgabewert speichert, den Namen result zu geben.
Normale Prozeduren sollen gar keine RETURN-Anweisung enthalten.
2.7 Verschachtelung und Länge von Programmteilen
Aus Gründen der Lesbarkeit dürfen Konstrukte nicht beliebig verschachtelt und Programmteile
nicht beliebig lang sein. Wenn hier von Zeilen gesprochen wird, so sind
logische Programmzeilen gemeint. Dabei bildet jede Anweisung oder Deklaration
eine eigene Zeile, unabhängig von der tatsächlichen Formatierung in der Datei.
• Die maximale Schachtelungstiefe von Prozeduren ist zwei. Das bedeutet, dass
höchstens eine Prozedur in eine Prozedur in einem Modul eingeschachtelt werden
darf.
• Innerhalb von Prozeduren sollen maximal fünf Konstrukte (IF, WHILE, REPEAT,
FOR, LOOP, CASE, WITH) ineinander geschachtelt werden.
• Jede Anweisung und jede Deklaration steht in einer eigenen Zeile.
• Eine Prozedur soll aus höchstens 40 Zeilen bestehen.
• Ein Implementierungsmodul soll maximal 800 Zeilen umfassen.
• Ein Definitionsmodul soll maximal 25 Funktionen, Variablen und Konstanten
umfassen. Diese Restriktion ist allerdings nicht in allen Fällen wirklich sinnvoll
(z.B. in Modulen, die nur Konstanten exportieren) und darf dann auch übergangen
werden.

Programmierrichtlinien für Modula-2 RR, 15.10.1999 7
• Eine Prozedur soll höchstens fünf Parameter besitzen. Ausnahmen sind nur in
begründeten Fällen zulässig.
3 Namenskonventionen
Dieser Abschnitt beschreibt, wie Namen vergeben werden sollen. Namen sind dabei
Bezeichner für Variablen, Konstanten, Typen, Prozeduren, Module, usw. Der erste
Abschnitt beschreibt die gemeinsamen Merkmale, die folgenden Abschnitte die
Besonderheiten einzelner Klassen von Namen.
3.1 Allgemeines
Alle Namen sind in Englisch. Namen dürfen sich nur aus großen oder kleinen Buchstaben
und aus Ziffern zusammensetzen. Der Unterstrich soll nicht verwendet werden,
außer um die Lesbarkeit ansonsten verwirrender Bezeichner zu erhöhen. Dann
darf er nur zwischen Worten stehen.
Namen sollen grundsätzlich so gestaltet werden, dass sie leicht lesbar, gut verständlich
und weitgehend selbsterklärend sind (sprechende Bezeichner). Außerdem sollen
sie dazu beitragen, dass der Programmtext in seiner Gesamtheit leicht lesbar und verständlich
ist. Es gelten die folgenden Regeln:
• Namen werden aus kurzen Wörtern zusammengesetzt, die die Bedeutung des
Bezeichners deutlich machen. Die Wörter werden direkt hintereinandergeschrieben.
Beispiel: NamingExample.
• Jedes Wort eines Namens beginnt mit einem Großbuchstaben, der Rest des
Worts wird klein geschrieben. Einzige Ausnahme ist das erste Wort des Bezeichners
einer Variablen oder eines formalen Parameters. Dieses wird vollständig
klein geschrieben. Beispiel: anotherNamingExample.
• Abkürzungen ermöglichen kürzere, aber dennoch verständliche und aussagekräftige
Bezeichner. Die Verwendung von Abkürzungen wird empfohlen; sie
müssen allerdings im Kommentar erklärt werden. Beispiel: otherNamingExpl.
• Da lange Bezeichnern zwar eine gute Erklärung liefern, aber die Programme
unleserlich und nicht mehr vernünftig formatierbar machen, ist ein Kompromiss
bei der Bezeichnerlänge nötig. Als Richtwert wird eine maximale Bezeichnerlänge
von 15 Zeichen vorgeschlagen.
• Bezeichner aus einem oder zwei Buchstaben sind nur in einem sehr lokalen Kontext
zulässig, z.B. für Schleifenvariablen. Ansonsten sind derart aussagearme
Bezeichner zu vermeiden.
• Die Überdeckung sichtbarer Bezeichner durch lokale Bezeichner soll vermieden
werden, da es zu Verwirrung führen kann.
• Für unterschiedliche Aufgaben sollen nicht dieselben Bezeichner verwendet
werden, auch wenn sich die Bezeichner durch die Sichtbarkeitsregeln von Prozeduren
und Modulen nicht überdecken können.
• Ziffern sollen in Bezeichnern nur sehr sparsam eingesetzt werden.
Wie bei vielen Dingen kommt es auch bei der Wahl der Bezeichner auf eine konsistente,
nachvollziehbare Verwendung und eine gute Dokumentation an.

Programmierrichtlinien für Modula-2 RR, 15.10.1999 8
3.2 Module
Modulnamen stehen für eine Kategorie von Dingen. Sie sollen mit Substantiven
bezeichnet werden. Beispiel: Terminal. Für ein Modul, das einen abstrakten Datentyp
exportiert, ist es oft sinnvoll, die Pluralform des Typnamens zu wählen. Beispiel:
Lists, Stacks.
3.3 Prozeduren
Prozeduren tun etwas. Daher sollen Prozedurnamen Verbkonstruktionen sein. Der
Bezeichner gibt eine kurze, anschauliche Beschreibung der Aktion in Befehlsform.
Beispiel: ClearScreen, CountSheep, Pop.
Funktionsprozedurnamen stehen für den Wert, den die Funktionsprozedur zurückgibt.
Der Name kann zusätzlich mit dem Präfix Get versehen werden. Beispiele:
ScreenNumber, GetDate.
3.4 Variablen
Variablennamen machen Aussagen darüber, welche Bedeutung der Wert der Variable
im aktuellen Kontext hat. Beispiele: speed, result, freeMemory. Kurze Variablennamen
wie i, j sind nur in sehr begrenztem Kontext erlaubt, z.B. als Namen einer
Schleifenvariable.
Parameternamen und die Namen von RECORD-Komponenten sind wie Variablennamen
zu bilden.
3.5 Konstanten
Der Name einer Konstante sagt aus, welche Bedeutung ihr Wert hat. Konstantennamen
sind in der Regel Substantive mit Adjektiven. Beispiel: MaxLength.
3.6 Typen
Ein Typname beschreibt eine Wertemenge. Daher soll es sich um ein Substantiv handeln.
Es ist zur Unterscheidung von Variablen des Typs oft sinnvoll, das Wort Type
anzuschließen. Beispiele: Stack, TreePointer, TreeNodeType. Die Elemente eines
Aufzählungstyps sind wie Konstanten zu behandeln.
4 Formatierung
In diesem Abschnitt wird festgelegt, wie die einzelnen Programmkonstrukte zu formatieren
sind.
4.1 Allgemeines
Eine einheitliche, lesbare und übersichtliche Darstellung des Programmcodes erleichtert
dem Leser das Verständnis und fördert den Überblick. Die folgenden Regeln dienen
daher einer möglichst einheitlichen Gestaltung.
Die Formatierung verfolgt die folgenden Ziele:
• Die Gliederung des Programmtextes soll der logischen Struktur des Programms
folgen und diese optisch unterstützen.

Programmierrichtlinien für Modula-2 RR, 15.10.1999 9
• Das Programm soll sowohl am Bildschirm als auch auf Papier gut lesbar und
bearbeitbar sein.
• Die optische Darstellung soll in gewissem Rahmen mit dem intuitiven Verständnis
des Lesers korrespondieren.
4.2 Einrückungen, Abstände, Ausrichtung
Die Zeilenlänge ist auf 79 1 Zeichen beschränkt. Auf diese Weise ist der Programmtext
auf den meisten Terminals, in den meisten Editoren und über die meisten Drucker auf
Papier relativ problemlos ohne lästige Umbrüche oder abgeschnittene Teile darzustellen.
4.2.1 Einrückung und Schachtelung
Jede Einrückung erfolgt mit zwei zusätzlichen Leerzeichen, also pro Stufe um zwei
Zeichen. Die oberste Stufe beginnt in der ersten Spalte. Für die Einrückungen dürfen
nur Leerzeichen verwendet werden. Tabulatoren sind nicht erlaubt, da sie nicht auf
allen Geräten zur selben Einrückung führen.
Für die Einrückung gilt die folgende Regel: Bei Verschachtelungen wird pro Stufe um
die oben angesprochenen zwei Zeichen eingerückt. Dabei werden die Schlüsselwörter,
die die Einschachtelung umschließen, noch nicht eingerückt.
BEGIN
WHILE IsBusy(printer) DO
Wait(10); (* wait 10 seconds *)
END;
PrintFile(printer,file);
END;
Kommentare werden genauso weit eingerückt wie die zugehörigen Programmzeilen.
4.2.2 Umbruch zusammengehörender Zeilen
Fortgesetzte Zeilen werden wie Schachtelungen eingerückt. Allerdings soll die Einrückung
eine weitere Stufe tiefer erfolgen, wenn eine logische Struktur (z.B. Klammern
in einem Ausdruck oder die Bedingung in einer IF-Anweisung) dies impliziert.
endNumber := middleNumber + nextNumber
+ anotherNumber; (* indentation is 2 blanks *)
IF ((endNumber + middleNumber)
< anotherNumber) THEN (* indentation is 4 blanks *)
Beim Trennen von Zeilen soll an einer möglichst sinnvollen Stelle getrennt werden.
Normalerweise stehen an der Trennstelle Operatoren; diese werden an den Anfang
der fortgesetzten Zeile gesetzt. Auf diese Weise ist diese leicht als Fortsetzung zu
erkennen und wird beim schnellen Lesen nicht als eigene Anweisung angesehen.
1. Diese Zahl ergibt sich aus der üblichen Zeilenlänge von 80 Zeichen, wenn man berücksichtigt,
dass viele Editoren (z.B. Emacs) das 80. Zeichen bereits in die nächste Zeile umbrechen,
damit sie in der Spalte 80 diesen Umstand durch ein Sonderzeichen anzeigen können.

Programmierrichtlinien für Modula-2 RR, 15.10.1999 10
4.2.3 Horizontale Abstände
Horizontale Abstände, also Leerraum zwischen einzelnen Bezeichnern, Trennern, Operatoren
usw., erhöhen die Lesbarkeit des Programmtextes und implizieren eine gewissen
Gruppierung. Grundsätzlich sollen die Abstände so gewählt werden, wie man
dies von üblichem Prosa-Text und mathematischen Formeln gewohnt ist. Die
Abstände werden aber auch zu einer gewissen Gruppierung verwendet, vor allem in
Formeln.
Die folgende Regeln für das Setzen von horizontalen Abständen werden empfohlen:
• Vor und hinter folgenden Operatoren und Trennern steht Leerraum:
+ - * / < = > = # := .. |.
• Hinter den unären Operatoren ~, + und - steht kein Leerraum, jedoch davor.
• Nach einem Komma, einem Doppelpunkt oder einem Semikolon steht Leerraum,
davor nicht. Leerraum hinter einem Komma kann weggelassen werden.
• Klammern stehen grundsätzlich ohne führenden oder folgenden Leerraum.
d := RealMath.sqrt((a * a) + (b * b));
Leerraum hinter öffnenden und vor schließenden Klammern ist zulässig, um
verschachtelte Ausdrücke oder Aufrufe besser strukturieren zu können.
( -b - sqrt( (b * b) - (4.0 * a * c) ) ) / (2.0 * a)
• Zwischen dem Prozedurnamen und seiner Parameterliste steht kein Leerraum.
Normalerweise werden horizontale Abstände durch ein Leerzeichen (oder einen Zeilenumbruch)
gebildet. Zur vertikalen Ausrichtung von Operatoren können auch
mehrere Leerzeichen eingefügt werden.
4.2.4 Vertikale Abstände
Vertikale Abstände werden durch Leerzeilen gebildet. Hier gilt es im wesentlichen zwei
Effekte abzuwägen. Zum einen wird der Programmtext durch Leerzeilen lockerer
und besser gegliedert. Zusammenhängende Programmteile sind leicht zu erkennen.
Auf der anderen Seite aber nehmen Leerzeilen sehr viel Raum in Anspruch, so dass
auf einer Bildschirmseite und vor allem auf einem Blatt Papier nur ein kleiner Ausschnitt
des Programms zu sehen ist. Darunter leidet die Übersichtlichkeit und die
schnelle Erfassung der Zusammenhänge.
Leerzeilen sollen dazu benutzt werden, logische Einheiten des Programmtextes zu
gruppieren. Da sich hierfür nur sehr schwer allgemeingültige Regeln aufstellen lassen,
folgen hier einige Regeln und Empfehlungen:
• Vor und hinter Prozedur- und Funktionsdeklarationen (einschließlich dem
zugehörigem Kopfkommentar) muss eine Leerzeile stehen.
• Die einzelnen Bestandteile von Modulen (Importe, Typdefinition, Variablendeklarationen,
Konstanten usw.) sollen durch Leerzeilen getrennt werden.
• Je länger eine Einheit ist, desto mehr Leerzeilen verträgt sie. So sollen Prozeduren,
die selbst wieder Prozeduren enthalten, wie Module behandelt werden, d.h.
die einzelnen Deklarationsteile können hier ebenfalls durch Leerzeilen getrennt
werden.

Programmierrichtlinien für Modula-2 RR, 15.10.1999 11
• In Definitionsmodulen können einzelne Prozedur-, Variablen-, Typ- und Konstantengruppen
wieder durch Leerzeilen in Untergruppen aufgeteilt werden. Es
ist jedoch nicht sinnvoll, dass vor und hinter jeder Deklaration eine Leerzeile
steht.
4.2.5 Ausrichtung von Operatoren und Begrenzern
Programmtext wird leichter lesbar, wenn in zusammenhängenden Programmteilen
korrespondierende Operatoren und Begrenzer direkt untereinander stehen.
temp := field1;
field1 := field2;
field2 := temp;
Die Ausrichtung der Zuweisungsoperatoren soll nur dann erfolgen, wenn zwischen
den Zeilen ein inhaltlicher Zusammenhang besteht. Gegenbeispiel:
val := (A * B) + C;
fileAtEOF := TRUE;
Die Ausrichtung von Operatoren und Klammern bietet sich natürlich besonders bei
Formeln an, die über mehrere Zeilen gehen. Auf diese Weise kann in langen und komplexen
Formeln eine zusätzliche Gruppierung erreicht werden. Schreibfehler fallen so
auch besser auf.
Deklarationen sollen nach Möglichkeit immer vertikal an den Doppelpunkten oder
Gleichheitszeichen ausgerichtet werden.
VAR
val : REAL;
counter: INTEGER;
Analog hierzu sollen auch die Deklarationsteile von Record-Deklarationen ausgerichtet
werden (vgl. Abschnitt 4.5.2).
Eine entsprechende Ausrichtung soll auch in den Parameterlisten von Prozedur- und
Funktionsdeklarationen verwendet werden. Dort werden die Doppelpunkte, die
Parametermodi und die Bezeichner vertikal ausgerichtet.
PROCEDURE DisplayMenu( title : Text;
VAR choice: ChoiceType);
4.3 Kontrollstrukturen
Die folgenden Muster geben die Formatierung verschiedener Kontrollstrukturen vor.
Platzhalter für Bezeichner oder anderen Code sind kursiv gesetzt. Man beachte, dass
ein Teil der hier gezeigten Syntaxelemente (z.B. der ELSE-Zweig in der IF-Anweisung)
optional ist.
4.3.1 Blöcke
BEGIN
Anweisungen
END;

Programmierrichtlinien für Modula-2 RR, 15.10.1999 12
4.3.2 Bedingte Anweisungen
IF Bedingung THEN
Anweisungen
ELSIF Bedingung THEN
Anweisungen
ELSE
Anweisungen
END;
CASE Ausdruck OF
| ErsteAuswahl:
Anweisungen
| ZweiteAuswahl:
Anweisungen
...
ELSE
Anweisungen
END;
4.3.3 Schleifen
Hier wird am Beispiel einer WHILE- und REPEAT-Schleife das Prinzip demonstriert.
Die anderen Schleifen (FOR, LOOP) werden analog formatiert. Die WITH-Anweisung
wird analog zu den Schleifen formatiert.
WHILE Bedingung DO
Anweisungen
END;
REPEAT
Anweisungen
UNTIL Bedingung;
4.4 Importe
Für jedes importierte Modul ist eine IMPORT-Anweisung zu formulieren. Importe von
Modulen sind wie folgt zu formatieren:
IMPORT AnotherModule;
IMPORT YetAnotherModule;
Der Import einzelner Prozeduren aus einem Modul sieht wie folgt aus:
FROM FirstModule IMPORT
FirstProcedure, SecondProcedure;
Wird nur eine Prozedur importiert, kann statt eines Zeilenumbruchs ein Leerzeichen
verwendet werden.
FROM FirstModule IMPORT SingleProcedure;
4.5 Deklarationen
Deklarationen und Instantiierungen gleichartiger Strukturen (z.B. aller Felder eines
Records) werden tabellenartig notiert. Die notwendige horizontale Ausrichtung
wurde in Abschnitt 4.2.5 bereits angesprochen.

Programmierrichtlinien für Modula-2 RR, 15.10.1999 13
4.5.1 Allgemeines
Die Deklarationen werden wie alle übrigen Blöcke unter dem Schlüsselwort eingerückt.
Deklarationen sind hier Variablen- (VAR), Konstanten- (CONST) und Typdeklarationen
(TYPE).
TYPE
Deklaration1;
Deklaration2;
Falls nur eine Element deklariert werden soll, kann dieses auch direkt hinter dem
Schlüsselwort stehen.
CONST MaxLength = 100;
Oft sind die Werte von Konstanten recht umfangreich. Dies gilt insbesondere für Zeichenketten.
Sollten diese nicht mehr in eine Zeile passen, so werden sie doppelt eingerückt
in eine neue Zeile geschrieben. Der Zuweisungsoperator bleibt dabei in der ersten
Zeile.
CONST
LongText =
"This is a text that goes on and on and on.";
MaxLength = 100;
Alle Deklarationen werden dabei weiterhin auf den Doppelpunkt bzw. das Gleichheitszeichen
vertikal ausgerichtet.
4.5.2 Records
Hier wird die Formatierung eines Record ohne und mit variantem Teil gezeigt. Bei
varianten Records wird der eingeschachtelte CASE-Teil analog zur CASE-Anweisung
formatiert. Der variante Teil muss als erste Komponente des Record deklariert werden.
TYPE
Name = RECORD
eineKomponente : Typ;
weitereKomponente: Typ;
END;
TYPE
Name = RECORD
CASE markenFeld: Typ OF
| ErsteAuswahl:
eineKomponente1 : Typ;
weitereKomponente1: Typ;
| ZweiteAuswahl:
eineKomponente2 : Typ;
weitereKomponente2: Typ;
...
END;
eineKomponente : Typ;
weitereKomponente: Typ;
END;

Programmierrichtlinien für Modula-2 RR, 15.10.1999 14
4.6 Prozeduren
Prozeduren und Funktionsprozeduren werden (bis auf die Angabe des Rückgabewertes)
gleich formatiert.
PROCEDURE ProzedurName(Parameterliste);
Deklarationen
BEGIN
Anweisungen
END Name;
PROCEDURE FunktionName(Parameterliste): Rückgabetyp;
Deklarationen
BEGIN
Anweisungen
END Name;
Bei Prozedurdeklarationen im Definitionsmodul wird natürlich der Rumpf weggelassen.
Die Parameterlisten werden folgendermaßen formatiert (hier beispielhaft):
PROCEDURE Equal(left : List;
right: List): BOOLEAN;
Wertparameter müssen zuerst aufgeführt werden, dann folgen die Referenzparameter.
Hier gibt es allerdings eine Ausnahme: Bei Prozeduren eines abstrakten Datentyps,
die einen Parameter vom abstrakten Typ erhalten, wird dieser Parameter immer
als erster notiert, auch wenn er ein Referenzparameter ist. Damit soll klar werden, auf
welchem Objekt die Aktion stattfindet.
Für jeden Parameter sollte der Typs explizit hingeschrieben werden; Parameter desselben
Typs sollten daher nicht durch Kommata aufgezählt werden. Statt
besser
PROCEDURE InsertAt(VAR list: List;
item, pos : CARDINAL);
PROCEDURE InsertAt(VAR list: List;
item: CARDINAL;
pos : CARDINAL);
schreiben, dann kann man besser erkennen, wieviele und welche Parameter eine Prozedur
hat.
4.7 Module
Module sind wie folgt formatiert (hier am Beispiel eines Hauptmoduls)
MODULE Name;
Importe
Deklarationen
BEGIN
Anweisungen
END Name.
Die Importe und Deklarationen werden wie oben beschrieben aufgebaut und durch
Leerzeilen gegliedert.

Programmierrichtlinien für Modula-2 RR, 15.10.1999 15
5 Kommentierung
Dieser Abschnitt beschreibt den Aufbau von Kommentaren innerhalb eines Programms.
5.1 Allgemeine Hinweise zur Kommentierung
Wenn Programme nach einiger Zeit weiterentwickelt, gewartet oder verstanden werden
sollen, ist eine Kommentierung unerlässlich. Grundsätzlich gilt, dass undokumentierte
Programme nicht akzeptabel sind. Andererseits sollten Programme immer
so geschrieben sein, dass erklärende Kommentare zum Code weitgehend überflüssig
sind. Dies in den meisten Fällen möglich, wenn auch häufig nur durch mehrere Überarbeitungen
des Codes.
Alle Kommentare sind in Englisch. Es dürfen nur die Zeichen des ASCII-Zeichensatzes
(7-Bit-ASCII) verwendet werden. Damit sind alle Sonderzeichen aus einem erweiterten
ASCII-Zeichensatz unzulässig. Auf diese Weise entfallen die typischen Probleme
beim Drucken, bei der Bildschirmdarstellung und bei der Eingabe.
In den folgenden Abschnitten wird angegeben, wie Kommentare zu formatieren sind.
Es soll dabei aber immer darauf geachtet werden, dass sich Kommentar und Programm
deutlich voneinander abheben und nicht verwechselt werden können. Im
Notfall ist zusätzlicher Leerraum zur Trennung einzufügen.
Kommentare ergänzen den Programmcode. Es gelten daher folgende Grundregeln:
• Kommentare sollen klar, kurz und verständlich sein. Ziel ist eine knappe, stichwortartige
Vermittlung der notwendigen Informationen zum Programm.
• Kommentare bilden die einzige Chance des Programmierers, seine Überlegungen,
seine Intention und seine Entscheidungen dem Leser mitzuteilen. Davon
soll reichlich Gebrauch gemacht werden.
• Alle Kommentare sollen immer auf dem aktuellen Stand gehalten werden und
nicht erst nachträglich eingefügt oder angepasst werden.
• Kommentare erklären im Allgemeinen, warum etwas so programmiert wurde.
Wenn nicht aus dem Code klar hervorgeht, wie eine Aufgabe gelöst wird, soll
dies in kurzen Kommentaren erläutert werden. Es kann dabei zum Beispiel auch
auf andere Quellen (z.B. Algorithmenbücher) verwiesen werden.
• Kopfkommentare und eingeschobene Kommentare strukturieren den Code und
erklären abschnittsweise, was der folgende Teil tut.
• Kommentare geben einen Überblick über den Aufbau des Programms und
beschreiben auch Zusammenhänge, die sich nicht direkt aus dem Programm
ergeben oder über mehrere Dateien, Module oder Prozeduren verteilt sind.
• Kommentare geben nicht direkt ersichtliche Voraussetzungen an, von denen an
einer bestimmten Stelle ausgegangen wird. Wenn der Programmierer solche
Bedingungen im Hinterkopf hat, soll er sie für den Leser des Programms sichtbar
machen, indem er sie in einem Kommentar niederlegt.

Programmierrichtlinien für Modula-2 RR, 15.10.1999 16
5.2 Kopfkommentare
Durch Kopfkommentare werden die verschiedenen Einheiten eines Programms gegliedert.
Kopfkommentare erläutern grob den Inhalt der folgenden Einheit und helfen
dem Leser und Programmierer beim Navigieren innerhalb der verschiedenen Programmdateien.
Kopfkommentare haben zusätzlich eine administrative Aufgabe. Sie
geben den Erstellungszeitpunkt, den Autor und Ähnliches an.
Kopfkommentare beginnen in der Spalte, in der auch der nachfolgende Code beginnt.
Sie haben im Gegensatz zu den anderen Kommentaren ein festes Layout, das in den
folgenden Unterabschnitten beschrieben wird. Jeder Teil eines Kopfkommentars wird
durch ein besonderes Schlüsselwort eingeleitet, gefolgt von einem Doppelpunkt. Der
zugehörige Text beginnt in der folgenden Zeile und wird unter dem Schlüsselwort
eingerückt. Falls der Text kurz genug ist, kann er auch direkt hinter das Schlüsselwort
geschrieben werden.
Die Anmerkung ‚(optional)‘ bedeutet, dass der betreffende Teil nicht zwingend erforderlich
ist. Falls es zu diesem Punkt aber Wichtiges zu sagen gibt, sollte der Teil in den
Kopfkommentar aufgenommen werden.
5.2.1 Module
Im Kopfkommentar jedes Moduls, egal ob Hauptmodul, Definitionsmodul oder
Implementierungsmodul, sind folgende Informationen niederzulegen:
1. FILE: Name der Datei. Dies ist hilfreich, um einen Papier-Ausdruck einer Datei
zuordnen zu können.
2. PROJECT: Projektidentifikation. Im Rahmen des Programmierkurses ist dies die
Aufgabenblatt- und Aufgabennummer.
3. CREATED: Erstellungsdatum der Datei.
4. VERSION (optional): Aktuelle Version der Datei mit Datum. Diese Information
wird normalerweise von Werkzeugen zum Configuration Management aktualisiert
1 , eine Aktualisierung von Hand ist etwas mühsam. Es wird dennoch empfohlen,
diese Information im Kopfkommentar zu haben und mitzuführen.
5. AUTHOR: Name des oder der Autoren. Im Rahmen des Programmierkurs auch
die Gruppennummer.
6. DESCRIPTION: Beschreibung des Moduls. An dieser Stelle wird der Zweck des
Moduls und dessen Leistungsumfang beschrieben.
7. RESTRICTIONS (optional): Restriktionen. Welche Einschränkungen oder Sonderfälle
sind zu beachten?
8. NOTES (optional): Bemerkungen aller Art.
9. MODIFICATIONS: Die Änderungshistorie. Hier werden unter Angabe des
Datums und des Autorenkürzels die Veränderungen tabellarisch aufgelistet. Die
entsprechenden Erläuterungen werden dabei recht knapp gehalten.
Definitionsmodul. Der Kopfkommentar eines Definitionsmoduls soll alle Informationen
enthalten, die ein Verwender des Moduls benötigt (mit Ausnahme der Beschrei-
1. Zum Beispiel kann man bei VERSION den String $Id$ eintragen, dann wird von RCS automatisch
beim Ein- und Auschecken die komplette Versionsinformation eingefügt.

Programmierrichtlinien für Modula-2 RR, 15.10.1999 17
bung der Prozeduren, die bei den einzelnen Prozeduren erfolgt). Bei Definitionsmodulen
soll daher die Beschreibung (unter DESCRIPTION) ausführlich ausfallen.
Folgende Punkte sollen dort zusätzlich beschrieben werden.
• Verwendung des Paketes: Eine grobe Beschreibung der Anwendung des Paketes.
Diese beschäftigt sich vor allem mit der sinnvollen und vorgeschriebenen
Reihenfolge der Funktionsaufrufe.
• (optional) Hinweise auf die Behandlung globaler, also mehrere Teile des Paketes
betreffender Fehler. Hier geht es um prinzipielle Fehler und Fehlerbehandlungsstrategien
aus Anwendersicht.
(*
FILE : ~reissing/modula/lib/Lists.def
PROJECT: ADTs for the Programming Course
CREATED: Fri Oct 11 15:38:01 MET DST 1996
VERSION: 1.3, Fri Nov 28 11:34:23 MET 1997
AUTHOR : Ralf Reissing
DESCRIPTION:
ADT List with a lot of operations.
'Create' creates an empty list and should be called
before any other operation
NOTES:
Caution! Interface is under construction!
MODIFICATIONS:
1997/11/28 RR renamed procedure GetItem to ItemAt
1997/10/22 RR added procedures IsEmpty and Size
*)
DEFINITION MODULE Lists;
Implementierungsmodul. Die Kommentierung des Implementierungsteils
beschränkt sich auf die Beschreibung der Realisierung. Im Kopfkommentar des
Implementierungsmodul soll das Wartungspersonal und der Programmierer die notwendigen
Informationen finden. Informationen aus dem Definitionsmodul brauchen
nicht wiederholt zu werden. Im Folgenden werden die Besonderheiten des Kopfkommentars
für ein Implementierungsmodul beschrieben.
Der Punkt IMPLEMENTATION ersetzt den Punkt DESCRIPTION.
• IMPLEMENTATION: Angaben zur Implementierung. In diesem Abschnitt soll
kurz die Grundidee der Realisierung des Moduls beschrieben werden. Der
Abschnitt ist nicht optional und muss daher auch dann im Kopf verbleiben,
wenn es absolut nichts zur Realisierung und der dahintersteckenden Strategie
zu sagen gibt.
Der Punkt RESTRICTIONS gibt hier Auskunft über Einschränkungen der Implementierung
gegenüber der Definition.
5.2.2 Prozeduren
Prozeduren erhalten Kopfkommentare, die sie als Ganzes beschreiben. Da auch bei
Prozeduren zwischen Deklaration (im Definitionsmodul) und Definition (im Implementierungsmodul)
unterschieden wird und es andererseits auch lokale Prozeduren
ohne Deklaration geben kann, gibt es drei leicht unterschiedliche Kopfkommentarstrukturen.

Programmierrichtlinien für Modula-2 RR, 15.10.1999 18
Deklaration. Im Kopfkommentar einer Deklaration werden analog zum Kopfkommentar
eines Definitionsmoduls alle Informationen übermittelt, die für die Verwendung
der Prozedur notwendig sind.
1. PROCEDURE (optional): Der Name der Prozedur. Bei längeren Kopfkommentaren
muss man erst am Ende nachschauen, um welche Prozedur es überhaupt
geht. Daher ist es häufig sinnvoll, bereits zu Beginn des Kopfkommentars anzugeben,
um welche Prozedur es sich handelt.
2. DESCRIPTION: Beschreibung der Funktionalität der Prozedur aus der Sicht
eines Benutzers, der das Innenleben der Prozedur nicht kennt. Die Beschreibung
soll ausreichen, um zu verstehen, was die Prozedur leistet.
3. PARAMETERS: Auflistung der Parameter (nur Name) und ihrer Bedeutung.
4. RETURNS (nur bei Funktionsprozeduren): Auflistung der möglichen Rückgabewerte
und deren Bedeutung.
5. PRE (optional): Vorbedingungen geben an, welche Bedingungen erfüllt sein
müssen, damit die Prozedur erfolgreich ausgeführt werden kann.
6. POST (optional): Nachbedingungen geben an, welche Bedingungen erfüllt sind,
nachdem die Prozedur erfolgreich ausgeführt werden konnte.
Vor- und Nachbedingung sind vor allem bei der Deklaration von Operationen auf
einem abstrakten Datentyp sinnvoll. Der Wert eines Parameters p zum Zeitpunkt des
Aufrufs wird mit p, zum Zeitpunkt des Verlassens mit p' notiert. Der Rückgabewert
einer Funktionsprozedur kann durch result benannt werden.
(*
PROCEDURE:
ItemAt
DESCRIPTION:
returns the pos-th item in the list (1 = first)
PARAMETERS:
list: the list
pos : the element position in the list
RETURNS:
the pos-th item of the list
PRE:
1

Programmierrichtlinien für Modula-2 RR, 15.10.1999 19
2. DESCRIPTION: Beschreibung der Prozedur. An dieser Stelle reicht ein kurzer
Hinweis auf die Funktionalität, eine Wiederholung des Textes aus dem Spezifikationsteil
ist nicht erforderlich.
3. IMPLEMENTATION (optional): Erläuterung der Arbeitsweise der Prozedur. An
dieser Stelle wird die Prozedur aus realisierungstechnischer Sicht beschrieben.
Wichtig ist vor allem eine überblickartige Beschreibung des Vorgehens, der
Intentionen und Entwurfsentscheidungen, sowie eine Erklärung des zugrundeliegenden
Algorithmus.
4. NOTES (optional): Allgemeine Hinweise. Unter diese Überschrift können alle
Anmerkungen abgelegt werden, die einem Programmierer helfen könnten, die
Prozedur zu verstehen, zu verändern, zu ergänzen oder zu portieren.
(*
PROCEDURE:
ItemAt
DESCRIPTION:
returns the pos-th item in the list (1 = first)
IMPLEMENTATION:
advances list to pos-th item (i.e. pos-1 steps)
and returns it
NOTES:
no checks if pos is in bounds (guaranteed by precond.)
*)
PROCEDURE ItemAt(list: List;
pos : CARDINAL): INTEGER;
VAR i: CARDINAL;
BEGIN
FOR i := 1 TO (pos - 1) DO (* advance to pos-th item *)
list := list^.next;
END;
RETURN list^.item;
END ItemAt;
Lokale Prozeduren. Einen Spezialfall bildet die Kommentierung von Prozeduren, die
keine Trennung zwischen Deklaration und Implementierung kennen. Dies sind üblicherweise
lokale Prozeduren in Modulen und in anderen Prozeduren. Der Kopfkommentar
muss daher ein Art Vereinigung der oben gezeigten Köpfe bilden. Dieser Aufwand
ist in der Regel jedoch nur bei Prozeduren in Modulen gerechtfertigt, nicht
jedoch bei eingeschachtelten Prozeduren.
Ein vollständiger Prozedurkopfkommentar besteht aus den Teilen DESCRIPTION,
PARAMETERS und RETURNS der Deklaration und optional aus den Teilen IMPLEMEN-
TATION und NOTES der Definition.
Bei optionalen Teilen sollte man in jedem Einzelfall entscheiden, welche Abschnitte
wirklich gebraucht werden. Oft sind die Prozeduren einfach genug, um auch in einem
kurzen Kopfkommentar alle wichtigen Informationen zu vermitteln. Dies gilt insbesondere
für eingeschachtelte Prozeduren.

Programmierrichtlinien für Modula-2 RR, 15.10.1999 20
5.3 Eingeschobene Kommentare
Eingeschobene Kommentare (oder Überschriften) beginnen in der Spalte, in der auch der
nachfolgende Programmtext beginnt. Sie gehen meist nur über wenige Zeilen und
erläutern die folgenden Programmzeilen.
In eingeschobenen Kommentaren wird eine Zusammenfassung des folgenden Algorithmus
gegeben, der Sinn des Programmabschnitts erklärt oder der aktuelle ‘Status’
(angenommene Vorbedingungen usw.) aufgezeigt. Beispiel:
(* The unsorted elements are now sorted using the
QuickSort-Algorithm. See Sedgewick: “Algorithms” for
details about this algorithm. *)
5.4 Erläuterungen
Erläuterungen (oder Anmerkungen) sind kurze Kommentare zu einzelnen Programmzeilen.
Sie stehen direkt hinter den betreffenden Zeilen und werden mit mindestens
zwei Leerzeichen vom Programm abgetrennt. Stehen mehrere Erläuterungen untereinander,
so sollten diese in der gleichen Spalte beginnen. Ansonsten sind die Erläuterungen
möglichst weit nach rechts auszurücken. Muss eine Erläuterung in der nächsten
Zeile fortgesetzt werden, so wird diese ebenfalls eingerückt. Allerdings steht in
dieser Zeile dann kein Programmtext.
average := (val1 + val2) / 2;
(* calculate average*)
Erläuterungen sind normalerweise sehr kurz und stichwortartig abgefasst. Sie
beschreiben nur die Aktion in der betreffenden Zeile. Auf diese Weise werden in der
Regel auch Variablendeklarationen und Typdefinitionen kommentiert.
6 Beispiele
Am Beispiel eines (etwas übertriebenen) HelloWorld-Programms und eines abstrakten
Datentyps Stack kann das Aussehen eines richtlinienkonformen Programms nachvollzogen
werden.
6.1 Hauptmodul HelloWorld.mod
(*
FILE:
~reissing/prokurs/examples/HelloWorld.mod
PROJECT:
Beispiele zum Programmierkurs
CREATED:
Mon Nov 3 10:26:55 MET 1997
VERSION:
$Id: HelloWorld.mod,v 1.5 1998/10/23 08:03:21 reissing Exp reissing $
AUTHOR:
Ralf Reissing
DESCRIPTION:
Hello World program: outputs “Hello World” and exits
The output is defined in constant HelloWorldString;
output is done using procedure WriteLine
*)
MODULE HelloWorld;

Programmierrichtlinien für Modula-2 RR, 15.10.1999 21
IMPORT InOut;
CONST HelloWorldString = “Hello World”;
(* DESCRIPTION:
Prints the parameter string followed by a line break
PARAMETERS:
string - the string to be printed
*)
PROCEDURE WriteLine(string: ARRAY OF CHAR);
BEGIN
InOut.WriteString(string);
InOut.WriteLn;
END WriteLine;
BEGIN
WriteLine(HelloWorldString);
END HelloWorld.
6.2 Definitionsmodul Stacks.def
(*
FILE:
~reissing/prokurs/examples/Stacks.def
PROJECT:
Programmierkurs, Styleguide Example
CREATED:
Wed Dec 11 17:08:31 MET 1996
VERSION:
$Id: Stacks.def,v 1.7 1998/10/23 08:04:13 reissing Exp reissing $
AUTHOR:
Ralf Reissing
DESCRIPTION:
Standard stack datatype (Last-In-First-Out container)
Item type is currently set to CHAR, may be changed to any other type
Use Create to create a new stack, Destroy to get rid of one;
Push adds an item to the stack, pop removes one
Introduction to formal notation:
A stack can be denoted by a list of items. The leftmost item in the
list is the topmost item of the stack
e.g. if stack = c b a then the top item of stack is ‘c’
Let |stack| be the number of items on a stack.
MODIFICATIONS:
1997/11/06 RR Pop doesn’t return a value anymore
1997/11/06 RR Empty renamed to IsEmpty
1997/11/06 RR PROCEDURE entry added to head comments of procedures
1997/10/29 RR bug in formal notation example fixed:
top element was ‘a’, should be ‘c’
1997/10/27 RR Introduction to formal notation moved into module comment
*)
DEFINITION MODULE Stacks;
TYPE
Item = CHAR; (* or any other simple/opaque type *)
Stack;
(*
PROCEDURE:
Create
DESCRIPTION:

Programmierrichtlinien für Modula-2 RR, 15.10.1999 22
Creates a new empty stack
PARAMETERS:
none
RETURNS:
a new empty stack
PRE:
TRUE
POST:
Empty(result)
*)
PROCEDURE Create(): Stack;
(*
PROCEDURE:
Destroy
DESCRIPTION:
Destroys a stack and releases associated memory
PARAMETERS:
stack: the stack to be destroyed
PRE:
TRUE
POST:
stack’ undefined, memory released
*)
PROCEDURE Destroy(VAR stack: Stack);
(*
PROCEDURE:
Push
DESCRIPTION:
pushes an item on top of a stack
PARAMETERS:
stack: the stack the item is to be pushed on
item : the item to be pushed on the stack
PRE:
TRUE
POST:
Top(stack’)=item
let stack = c b a, then stack’ = item c b a
*)
PROCEDURE Push(VAR stack: Stack;
item: Item);
(*
PROCEDURE:
Pop
DESCRIPTION:
pops top item from the stack
PARAMETERS:
stack: the stack to be popped from
PRE:
NOT Empty(stack)
POST:
Size(stack’)=Size(stack)-1
let stack = c b a, then stack’ = b a
*)
PROCEDURE Pop(VAR stack: Stack);
(*
PROCEDURE:
Top

Programmierrichtlinien für Modula-2 RR, 15.10.1999 23
DESCRIPTION:
returns top item of the stack
PARAMETERS:
stack: the stack
RETURNS:
top item of the stack
PRE:
NOT Empty(stack)
POST:
let stack = c b a, then result = c
*)
PROCEDURE Top(stack: Stack): Item;
(*
PROCEDURE:
Size
DESCRIPTION:
returns the number of items on the stack
PARAMETERS:
stack: the stack
RETURNS:
number of items on stack
PRE:
TRUE
POST:
result = |stack|
*)
PROCEDURE Size(stack: Stack): CARDINAL;
(*
PROCEDURE:
IsEmpty
DESCRIPTION:
tells whether a stack is empty, i.e. if there are no items in it
PARAMETERS:
stack: the stack
RETURNS:
TRUE if Size(stack) > 0, else FALSE
PRE:
TRUE
POST:
result = (Size(stack) > 0)
*)
PROCEDURE IsEmpty(stack: Stack): BOOLEAN;
END Stacks.
6.3 Implementierungsmodul Stacks.mod
(*
FILE:
~reissing/prokurs/examples/Stacks.mod
PROJECT:
Programmierkurs, Styleguide Example
CREATED:
Wed Dec 11 17:34:46 MET 1996
VERSION:
$Id: Stacks.mod,v 1.6 1998/10/23 08:04:54 reissing Exp reissing $
AUTHOR:
Ralf Reissing
IMPLEMENTATION:

Programmierrichtlinien für Modula-2 RR, 15.10.1999 24
stack is implemented using a simple linked list
top item is front element of the list
empty stack is represented by a NIL value
MODIFICATIONS:
1997/11/06 RR changed IMPORT-Format from FROM ... IMPORT To IMPORT ...
1997/11/06 RR adapted implementation of Pop and IsEmpty
to the interface changes
*)
IMPLEMENTATION MODULE Stacks;
IMPORT Storage;
TYPE
Stack = POINTER TO StackType;
StackType = RECORD
item: Item;
next: Stack;
END;
CONST StackTypeSize = SIZE(StackType);
(*
DESCRIPTION:
Creates a new empty stack
*)
PROCEDURE Create(): Stack;
BEGIN
RETURN NIL;
END Create;
(*
DESCRIPTION:
Destroys a stack and releases associated memory
IMPLEMENTATION:
Destroys stack by popping all items
*)
PROCEDURE Destroy(VAR stack: Stack);
BEGIN
WHILE NOT IsEmpty(stack) DO
Pop(stack);
END;
(* stack = NIL here *)
END Destroy;
(*
DESCRIPTION:
pushes an item on top of the stack
*)
PROCEDURE Push(VAR stack: Stack;
item: Item);
VAR newElement: Stack; (* stores newly created element *)
BEGIN
Storage.ALLOCATE(newElement,StackTypeSize);
newElement^.item := item; (* store item *)
newElement^.next := stack; (* prepend new element to stack list *)
stack := newElement;
END Push;
(*
DESCRIPTION:
pops top item from the stack

Programmierrichtlinien für Modula-2 RR, 15.10.1999 25
*)
PROCEDURE Pop(VAR stack: Stack);
VAR
auxiliary: Stack; (* stores item to be deallocated *)
BEGIN
auxiliary := stack; (* store element to be deallocated *)
stack := stack^.next; (* switch stack to next element *)
Storage.DEALLOCATE(auxiliary,StackTypeSize); (* dealloc 1st element *)
END Pop;
(*
DESCRIPTION:
returns top item of the stack
*)
PROCEDURE Top(stack: Stack): Item;
BEGIN
RETURN stack^.item;
END Top;
(*
DESCRIPTION:
returns the number of items in the stack
IMPLEMENTATION:
recursive solution: stack is virtually popped until it is empty
each successful virtual pop increments size by one
*)
PROCEDURE Size(stack: Stack): CARDINAL;
BEGIN
IF IsEmpty(stack) THEN
RETURN 0;
ELSE
RETURN 1 + Size(stack^.next);
END;
END Size;
(*
DESCRIPTION:
tells whether the stack is empty, i.e. if there are no items in it
*)
PROCEDURE IsEmpty(stack: Stack): BOOLEAN;
BEGIN
RETURN (stack = NIL);
END IsEmpty;
END Stacks.