=========================================================================== AMOK - Amiga Modula & Oberon Klub Standard Identifier für ProgInfo (Dokumentationsextraktion aus dem Quelltext) =========================================================================== Programmkopf Für alle AMOK-Programme ist ein Programmkopf vorgeschrieben, der die wichtigsten Informationen zu diesem enthält. Bei Modula-2- bzw. Oberon-Programmen muß er vor dem Schlüsselwort MODULE in einem Kommentar stehen. Er sollte durch "***"- oder "---"-Zeilen hervorgehoben sein, ein Einrahmen ist jedoch nicht zweckmäßig (da die letzten "*"s in der Zeile stören). Der Programmkopf enthält mehrere Einträge, die jeweils mit ":"Schlüsselwort"." beginnen. Reicht eine Zeile für einen Eintrag nicht aus, wird das ":"Schlüsselwort"." in der nächsten Zeile wiederholt und der Eintrag danach fortgesetzt. Doppelpunkt, Punkt und Schreibweise sind wichtig, da sonst die Einträge von Doku-Extraktionsprogrammen nicht gefunden werden. Der Programmkopf muß (!) mindestens folgende Einträge enthalten: :Program. :Contents. :Author. :Copyright. :Language. :Translator. :History. Falls notwendig müssen auch folgende Angaben gemacht werden: :Support. :Imports. :Bugs. Freiwillig sind diese Angaben: :Address. :Phone. :Update. :Remark. :Usage. Andere Einträge, Date, Shortcut, Version sind nicht mehr zu benutzen! Fehlende Einträge sollten so bald und gut als möglich nachgetragen oder rekonstruiert werden. Empfehlungen Auf eine strikte Festlegung des Programmkopftextes wurde verzichtet. Damit dieser jedoch einigermaßen einheitlich bleibt sollte man die folgenden Regeln beachten. Leere Einträge Außer den zuerst genannten Pflichteinträgen können eventuell auch welche entfallen. Am besten läßt man dann den gesammten Eintrag sammt Schlüssel- wort weg. Als leer gelten außerdem Einträge, die nur aus Leerzeichen, Sternchen "*" oder Strichen "-" bestehen. Unsinnige Einträge (zB. ":Imports. bis jetzt noch nichts") sind möglichst zu unterlassen. :Program. Hier sollte der Programmname stehen, der mit dem Filenamen (mit Extension, zB. "Test.def") übereinstimmen sollte. Reicht der Programmname zur eindeutigen Indentifizierung nicht aus (zB. geändertes Modul "Strings") so steht hinter dem Programmnamen ein entsprechender Kommentar. :Contents. Kurzbeschreibung von Programminhalt und -funktion. Die Beschreibung sollte erklärend sein und nicht nur eine längere Version des Programmnamens sein (zB. N I C H T : :Program. InOut.def :Contents. Definitionsmodul Input/Output ). :Author. Bitte den vollen Namen angeben. Pseudonyme sind unzulässig. Ein Programm kann auch mehere Autoren haben, zB. wenn ein PC-Programm auf den AMIGA umgesetzt wurde. :Address. Freiwillig ist die Angabe der Adresse des Autors. Sie sollte Straße, Hausnummer, Postleitzahl, Ort und Land enthalten. :Phone. Telefonnummer des Autors mit Vorwahl. Zusätzliche Bemerkungen, zB. Zeit- angaben für Erreichbarkeit, sind zulässig. Hat ein Programm mehere Autoren (siehe oben) so steht hier die Telefonnummer des für dieses Programm zuständigen Autors, d.h. desjenigen, der eventuelle Fragen am besten beantworten kann. :Copyright. Hieraus sollte ersichtlich sein, ob das Programm Freeware oder Shareware ist oder ob auf alle Rechte verzichtet wird (Public Domain). Freeware: - Der Autor legt die Kopierbestimmungen fest und - behält alle Rechte an seinem Programm Shareware: - Der Autor legt die Kopierbestimmungen fest - behält alle Rechte an seinem Programm und - erhebt bei regelmäßigem Gebrauch eine anerkennende Gebühr (Shareware-Gebühr), die gezahlt werden MUSS! Kommentare wie zB. "copy it, but leave my name in" oder ähnliches sind zulässig. Bei längeren "Plädoyers" sollte allerdings auf eine extra Datei verwiesen werden. :Language. Hier steht im Normalfall "Modula-2" bzw. "Oberon". Wenn das Programm INLINE-Assemblercode enthält, sollte dies hier Vermerkt werden. Ebenso sollte verfahren werden, wenn das Programm dem Modula-Standard nicht entsprechende Statements enthält. Dazu gehört unter anderem die seit M2Amiga v3.2 mögliche Typenkonversion von ADDRESS/BPTR und die Dereferenzierung von BPTRn (Zugriff auf BcplPtr^.items). Die normale Verwendung des Typs BPTR als opaker Typ gehört nicht dazu, denn er ist im Standard-Modula erlaubt. Der Sinn hiervon ist es, Leute zu warnen, die Programme auf andere Compiler umsetzen wollen. :Translator. Bezeichnet den Compiler (/Assembler/Interpreter) und die Versionsnummer (v1.17 oder v2.0). Dahinter stehen eventuelle Hinweise auf Compiler-Bugs, die für dieses Programm relevant sind. :History. Dies ist einer der wichtigsten Einträge. Er beinhaltet Informationen über die Versionen des Programms (Opfer), der entsprechenden Erstellungs- und Änderungsdaten (Tatzeit), den Autor oder für die Änderung Veratwortlichen (Täter) sowie eine optionale Bemerkung (Motiv). Beispiel: :History. v1.1 [bne] 29-Mar-89 bug in Init() fixed Den Versionsnummern wird später noch ein spezielles Kapitel gewidmet. Zusammengehörige Definitions- und Implementationsmodule tragen immer mindestens gleiche Versionsnummer (Revisionsnummer, Branchnummer und Kennbuchstabe dürfen verschieden sein). Das Datum besteht aus dem ein- oder zweistelligen Tag, dem Monatskürzel (Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dez) aus drei Buchstaben und der zwei oder vierstelligen Jahreszahl. Für den Autor steht sein Name Klammern (für Klubmitglieder das Kürzel). :Support. Der Fairneß halber sollte man hier Angaben über Beiträge anderer Personen sowie deren Namen machen, wenn man Schuldgefühle wegen geklauter Ideen oder Algorithmen hat. :Imports. Importiert das Modul außer den Standardmodulen des Compilers noch weitere, so müssen diese hier eingetragen werden. Wird eine bestimmte Version benötigt, folgt auf den Namen des importierten Moduls dessen Versionsnummer sowie der Autor. Es dürfen auch Verweise auf AMOK-Disks gemacht wedren. Beispiel: :Imports. MemSystem1.3 [bne], List [mif] AMOK#7 :Bugs. Sind Fehler eines Moduls bekannt, oder besteht der Verdacht, daß das Modul fehlerhaft ist, wird dies hier vermerkt. Soweit dies möglich ist, soll der Fehler möglichst eng eingegrenzt werden (zB Angabe der Prozedur, in der er auftritt). Ist ein Modul noch nicht vollständig ausgetestet, sollte man mit ":Bugs. not tested" warnen. ":Bugs. none" verpflichtet zu mindestens 99,9% Fehlerfreiheit! :Usage. bezeichnet die Syntax eines CLI-Befehls und dessen Argumente. Die Usage wird entweder in EBNF oder mit dem vom DOS-Handbuch und ARP verwendeten Template angegeben. Versionsnummern Die Versionsnummer besteht normalerweise aus zwei Stellen (version, revision), die durch einen Punkt getrennt sind. Die erste lauffähige Version wird mit 1.0 bezeichnet. Bei jeder Änderung wird die zweite Stelle (Revision) um eins erhöht, wobei nach 1.9 die 1.10 und dann 1.11 usw. folgt. Bei sehr tiefgreifenden Neuerungen wird die erste Stelle (Version) erhöht, die zweite (Revision) springt auf 0. Die Versionsnummer darf NICHT als Dezimalbruch angesehen werden, der sich jedesmal um 1/10 erhöht. Eine Revision ist KEINE zehntel Version und eine Version entspricht NICHT 10 Revisions. Version und Revision werden unabhängig gezählt!!! Versionsnummern wie 1.09 sind unzulässig und 1.10 (erste Version, zehnte Revision) steht zwischen 1.9 und 1.11 und ist nicht gleich 1.1 ! "Hundertstel" Versionen gibt es nicht. Wenn es erforderlich wird, eine Version nachträglich in eine Reihe einzufügen, wird dies durch eine zweiten Punkt gekennzeichnet. Beispiel:Es existieren bereits die Versionen 1.0 bis 1.4 , und jemand ändert nachträglich die Version 1.2 . Diese bekommt dann die Nummer 1.2.1 (sog. Branch-Version). Man kann Versionsreihen auch als Baum darstellen: 1.0 | V 1.1 | V 1.2 | / \ / \ V V 1.3 1.2.1 | | V V 1.4 1.2.2 | usw. ... | V 1.9 | V 1.10 usw. Die Zählweise entspricht nicht der von Big Blue, verleitet aber dafür zu weniger Mißverständnissen, weil man nicht rätseln muß, ob 3.2 jetzt die auf 3.1 oder auf 3.19 folgende Version ist. Version und Revision können beliebig hoch werden - Beispiel: die Libraries der alten 1.2 Workbench trugen die Versionsnummer 33.180 (dreiunddreißigste Version, hundertachzigste Revision). Wer noch eine feiner abgestufte Unterscheidung machen möchte, kann der Nummer noch einen Kleinbuchstaben anhängen. Dieser ist optional und muß nichts über die Reihenfolge aussagen (zB. 3.2d für die deutsche und 3.2e für die englische Version). Entsprechend dem Vorschlag von Bernd Preusing ist es jetzt doch zulässig, daß ein Implementationsmodul eine höhere Revisionsnummer hat wie das zugehörige Definitionsmodul. Dadurch ist es nicht nötig, wegen jeder Kleinigkeit das Definitionsmodul anzutasten, wodurch das Make viel Arbeit bekäme. Source-Code-Format Damit der Sourcecode einigermaßen übersichtlich ist, wird folgende Formatierung vorgeschlagen (nicht zwingend, nur übersichtlich muß es sein): * In jeder Zeile steht nur eine logische Anweisungseinheit. * Globale Prozeduren, Variablen und Konstanten stehen ganz am Anfang der Zeile. * Deklarationen und Prozedurkörper sind gegenüber ihrem CONST, VAR, TYPE und PROCEDURE eingerückt. * Programmteile, die lokal zu anderen definiert werden, oder von bestimmten Konstrukten eingeschlossen werden, werden jeweils relativ zu diesen um ZWEI Zeichen eingerückt. * Zusammengehörende BEGIN und END, IF, ELSE und END usw. stehen jeweils untereinander. Ist ein END mehr als eine Bildschirmseite (25 Zeilen) von seinem BEGIN etc. entfernt, steht hinter dem END in Kommentar, was dort beendet wurde. * Außer nach VAR, CONST, TYPE, BEGIN, DO, THEN, LOOP, RETURN und EXIT steht hinter jeder Zeile ein Semikolon. * Elemente von Mengen, Aufzählungstypen und RECORDs fangen klein an, Konstanten fangen klein oder groß an, alles andere immer groß. Zusammengesetzte Wörter haben auch in der Mitte "GrossBuchstaben". * Paßt die Parameterliste einer Prozedur nicht in eine Zeile (75 Zeichen), werden die Parameter untereinander angeordnet. * Importe werden alphabetisch nach den Namen der Module geordnet. Sind Importlisten länger als zwei Zeilen werden auch die importierten Objekte alphabetisch sortiert. MODULE Beispiel; CONST welches = 106; PROCEDURE TuWas(Dies: Typ; VAR Jenes: Art): BOOLEAN; CONST X = 1; Y = 10; VAR Zähler : INTEGER; BEGIN FOR Zähler := X TO Y DO Action(Dies, Jenes); END RETURN Jenes = welches END TuWas; BEGIN IF TuWas(etwas, irgendWas) THEN Aktion1; ELSE Aktion2; END; END Beispiel.