=========================================================================== AMOK - Amiga Modula & Oberon Klub Stuttgart "AMOK-Poster": Norm bzw. Standardform für AMOK-Beiträge Tips und Anhaltspunkte für Veröffentlichungen =========================================================================== Einleitung Wir -AMOK- sind gerne bereit, auch anderen Modula-2- bzw. Oberon- Programmierern mit den AMOK-Disks einen Weg zur Veröffentlichung Ihrer Programme zu bieten. Ziel unserer PD-Reihe ist es schließlich, für eine möglichst weite Verbreitung von Modula & Oberon zu sorgen. Da sich diese Programmiersprachen optimal zum Austausch von Programm-Modulen eignen, kann jeder Programmierer hierzu beitragen. Je größer die Modulbibliothek ist, auf die ein Programmierer zurückgreifen kann, desto weniger muß er sich mit zeitraubenden Alltagsproblemen herumschlagen und sozusagen "das Rad zweimal erfinden". Falls Sie also Module geschrieben haben, von denen Sie denken, daß auch andere sie gebrauchen können, schicken Sie sie an AMOK. Wenn irgend möglich werden wir den Beitrag in unsere AMOK-Reihe aufnehmen. Wir stellen zwar keine Ansprüche an die Genialität der Programme, damit Ihr Beitrag eine Chance hat, veröffentlicht zu werden, sollten Sie aber die unten aufgeführten Punkte beachten. Damit gewährleistet ist, daß Ihre PD-Software auch wirklich brauchbar ist. 1) Kriterien Wie schon erwähnt stellen wir keine Anforderungen an das, was ein Programm besonderes kann. Das was es kann, soll es aber sinnvoll und korrekt ausführen. Ein simples aber nützliches Modul hat, auch wenn es noch so banal ist, höhere Chancen, veröffentlicht zu werden, als ein Riesenprojekt, das an sich genial ist, aber ständig guru-meditiert. 2) AMOK Anforderungen Die Folgenden Punkte sind verbindlich und von jedem AMOK-Beitrag einzuhalten: * Zu jedem Modul(-packet) gehört eine Dokumentation. Ohne Dokumentation sind die Module für andere unbrauchbar. Es gibt auf den AMOK-Disketten folgende Formen der Dokumentation: - Dokumentation im Klartext in einer extra Datei mit der Endung ".dok" (für deutsche Dokumentation) oder ".doc" (für die englische) - stichwortartige Kurzbeschreibung der Prozeduren im Definitionsmodul Diese Form der Dokumentation ist auf AMOK# >= 25 bei "HeaderInfo" genauer beschrieben. Die Dokumentation sollte mindestens diese Informationen beinhalten: - Bedeutung und Auswirkung der Prozedurparameter - Funktion und Verwendungszweck der Prozeduren - Bedeutung der Rückgabewerte der Prozeduren - Wichtige Hinweise über exportierte Variablen, Konstanten und Typen - Hinweise auf mögliche Fehler (soweit bekannt) - Angaben über eventuelle Einschränkungen oder Warnungen Wenn möglich sollte die Dokumentation nur aus reinem ASCII-Code und nur mit den ANSI Steuersequenzen geschrieben werden. (MuchMore- und copy-to-prt:-verträglich) * Der Source-Code sollte den Modulen immer beigefügt werden. Schließlich sollen andere Programmierer aus Ihrem Programm etwas lernen können. Außerdem ist es somit möglich, eventuelle Fehler zu verbessern oder das Programm an eigene Bedürfnisse anzupassen. Als Ausnahmen sind folgende zulässig: - das Programm ist wirklich ausgesprochen genial und gehört eigentlich patentiert (es muß natürlich absolut fehlerfrei sein) - die Module sind Teile eines von Ihnen kommerziell vertriebenen Programms, und Sie wollen nicht, daß jemand Einblick erhält - Ihr Programmierstil ist so schlecht und Ihre Methoden so haar- sträubend, daß Sie den Source-Code niemandem zumuten wollen (In diesem Fall sollten Sie sich allerdings Überlegen, ob Sie nicht lieber C oder Assembler programmieren wollen) * Definitions und Implementationsmodul sollten unseren Modulkopf (siehe "HeaderInfo") beinhalten. Dieser ist zur leichteren Verwaltung der inzwischen mehrere Megabyte umfassenden AMOK-Softwarebibliothek notwendig. Bitte erfindet keine eigenen ShortCuts! Diese sind den Klubmitgliedern vorenthalten! Haltet Euch an unsere Formatvorgaben in "HeaderInfo". * Alle Dateien und Unterdirectories sollen Icons haben, so daß Sie von der Workbench aus zugänglich sind. Das Default-Tool von Textdateien (Source und Dokumentation) muß auf ":c/MuchMore" eingestellt sein. 3) AMOK Vereinbarungen Es wird gebeten, auch auf folgendes zu achten: * Sollten zum Compilieren eines Moduls noch andere nicht standardmäßige Module benötigt werden, sollten diese mitgeliefert werden. Dabei ist darauf zu achten, daß die sym-Schlüssel stimmen, d.h. alles mit der selben Version der Definitionsmodule compiliert wurde. Existieren von imortierten Modulen mehrere Versionen, dann ist anzugeben, welche benötigt wird. (Vermerk :Imports.) * Im Source-Code und in der Dokumentation sollte man wenn möglich die Zeilenlänge auf 70 bis 75 Zeichen begrenzen. MuchMore und M2Emacs akzeptieren zwar 80 Zeichen, viele möchten jedoch sicherlich die Texte ausdrucken, und da ist ein Rand ganz nützlich. * Prozedur-, Variablen-, Konstanten- und Typenbezeichner sollten vorzugsweise englisch sein, ebenso die Kurzbeschreibung der Prozeduren im Definitionsmodul (siehe AMOK#7, ProgInfo/StandardIDs). Wenigstens sollte man Englisch und Deutsch nicht mischen. Deutsche Dokumentation sollte nicht fehlen, englische ist freiwillig. * Kleine Demoprogramme dienen der leichteren Verständnis und dem besseren Einarbeiten in die Funktionen eines Moduls. Oft sind Testmodule oder sonstige Beispielanwendungen als Nebenprodukte eigener Programme sowieso vorhanden. * Seien Sie fair gegenüber anderen Programmierern. Public Domain heißt noch lange nicht "Software-Freiwild". Wenn Sie Programmteile von anderen übernehmen, erwähnen Sie den Autor bitte im Modulkopf oder in Kommentarzeilen. Für eine kommerzielle Nutzung brauchen Sie die Schriftliche Erlaubnis des jewiligen Autors. Denken Sie bitte auch an eventuelle Shareware-Gebühren. 4) Zum Thema korrekte Programme Die folgenden Anweisungen gelten nicht speziell für AMOK-Disketten sondern sollten von allen Programmierern beachtet werden. Wenn diese Punkte für Sie noch nicht selbstverständlich sind, empfehlen wir Ihnen DRINGENDST Ihre Programme in Zukunft dementsprechend auszulegen. * Alle Programme sollten auf korrektem Weg verlassen werden können, das heißt, ohne neu starten zu müssen, und so, daß uneingeschränkt weiter- gearbeitet werden kann. Außerdem sollen Sie alle Betriebsmittel und Resourcen an das System zurückgeben (Speicher deallozieren, Fenster, Screens und Files schließen). * Programme sollten sich nicht so verhalten, als wären Sie die einzigen im System, sondern auf das Multitasking und seine Restriktionen Rücksicht nehmen (z.B. gegenseitiger Ausschluß beim Zugriff auf System- strukturen). * Programme sollen sich gegenüber dem Benutzer logisch und bei Fehlein- gaben robust verhalten. * Man sollte nie davon ausgehen, immer alle Betriebsmittel zu bekommen, die man anfordert. Programme sollen sich definiert verhalten, wenn z.B. Files nicht geöffnet werden können, oder nicht mehr genügend Speicher vorhanden ist. * Die Benutzerschnittstelle soll den beim AMIGA allgemein üblichen Richt- linien entsprechen (siehe Intuition Reference Manual Chapter 12: Style). * Programme sollten wenn möglich keine spezielle Gerätekonfiguration vorraussetzen. * Besonders für die Entwicklung zukünftiger Bibliotheksmodule ist wichtig, daß die Prozeduren reentrant sind, falls es sinnvoll ist, sie von mehreren Tasks aus gleichzeitig zu benutzen (es ist in Modula ja nicht möglich, Module zweimal zu importieren). --- Viel Spaß