AppsWH-Programmierrichtlinien

Stand: 03. Mai 2012

• Arbeitsmittel
• Modulerstellung
  • ClassiX^® Konventionen
  • Transaktionshandling
  • Programmiervorgaben
  • Tipps und Tricks
• Dokumentation
  • Dokumentation im Modul
  • Dokumentation des Moduls in der Infothek
• Fehlerbehandlung
• Weiterentwicklung
• News
• Fehlermeldungen
• Transaktionsbeschreibungen und Workflows

1. Arbeitsmittel

2. Modulerstellung

Bei der Erstellung von neuen Modulen empfiehlt es sich mit dem ClassiX^®-Modulgenerator auf die Grundschablonen für AppsWh-Module zurückzugreifen. Der Modulgenerator wird zusammen mit dem Hilfegenerator und weiteren Tools im Unterverzeichnis .\Projects\Tools\ des ClassiX^®-Rootverzeichnis zur Verfügung gestellt.
In der Regel entsteht ein Dreigestirn in der Form Basis-, Editier- und Selektionsmodul, dessen Dateinamen sich an der darin hauptsächlich bearbeiteten Klasse ausrichten. Auch die Namen der in den Modulen verwandten Messages sollte sich an den angesprochenen Klassen orientieren.

2.1 ClassiX^® Konventionen

• Beim Programmieren und bei der Erstellung von neuen Modulen sind die Basisrichtlinien (vorgegeben durch den Modulgenerator (*.gen)) zu berücksichtigen
• Englisch ist Hauptsprache der Programmierung: Modul- und Variablennamen, Kommentare, etc. sind auf englisch anzugeben
  (Wenn ein englischer Begriff nicht bekannt ist, dann muss er nachgeschlagen werden)
• Der erste Buchstabe von Variablennamen ist immer klein, der von Widget-Namen und von Makros immer groß zu schreiben. Setzt sich der Name aus mehreren Wörtern zusammen, dann beginnen die folgenden Wörter jeweils mit einem großen Buchstaben.
• Variablennamen sollen so weit als möglich selbsterklärend sein (ggf. durch mehrere Worte). Dies gilt für Widget-Namen analog: Es sollten alle Widgets auch mit sinnvollen Namen belegt werden.
• Klassennamen und Messages werden in Großbuchstaben geschrieben. Sind diese aus mehreren Wörtern zusammengesetzt, dann erfolgt die Trennung durch Unterstriche (underscore).
• Einrückungen
  • Die Makrodefinition und das Semikolon am Ende des Makros wird grundsätzlich um 4 Leerzeichen eingerückt. Der Inhalt des Makros wird um weitere 2 Zeichen eingerückt.
  • bei geschweiften/eckigen Klammern, bei jeder Schleife und in allen case-Anweisungen werden die eingeschlossen Anweisungen um 2 Zeichen eingerückt.
• Kundenspezifische Änderungen
  • Kundenspezifisch abgeleitete Module enden mit einem Kundenkürzel
  • Kundenspezifische Pseudo-Klassen starten mit einem Kundenkürzel
• Messages dienen in der Regel der Kommunikation zwischen Modulen oder einzelnen Fenstern und nur in Ausnahmefällen nur innerhalb eines Fensters
• Direktes Ansprechen eines Widgets in einem anderen Fenster soll vermieden werden und über Messages geschehen
• SetFormat-Anweisungen für eine Objektliste sollten normalerweise im INITIALIZE-Block definiert werden, weil sie die Formatbeschreibung der Liste erweitern
• In SetFormat-Anweisungen sollen zum Aufrufen eines Makro nicht die veralteten Push()-Befehle, sondern call()-Ausdrücke benutzt werden
• Das Aussehen und die Funktionalität von FString-Feldern soll grundsätzlich von entsprechenden Zählern gesteuert werden
• Makro SetAllTxnManagers in Beleg-Modulen in INITIALIZE-Block aufrufen (und nicht bei jedem Verbuchen neu); in allen Kundenprojekten sollen REP-Collections CX_TXN_DESCRIPTOR indiziert werden
• Vor dem Modellieren von Daten muss dies mit einem ClassiX AppsWH Mitarbeiter abgestimmt werden. Dies sind Herr Brenner und Herr Röhl.

2.2 Transaktionshandling

Alle Transaktionen, welche auf die Datenbank zugreifen, machen automatisch eine Schreibtransaktion auf. Dies bedeutet, dass die Daten, auf welche zugegriffen wird, für die Dauer der Transaktion gesperrt sind. Für den Instantview Programmierer bedeutet dies folgendes:

• Kann in einer Transaktion sichergestellt werden, dass auf Daten nur lesend und nicht schreibend zugegriffen wird, so ist eine Lese-Transaktion über EndTXN BeginTXN(READ) zu starten. Eine bereits bestehende Transaktion würde das BeginTXN(READ) überlesen, daher ist es wichtig, dass mit EndTXN die eventuell bestehende Transaktion geschlossen wird.
• Für lange Transaktionen ist zu prüfen, ob diese in zwei Schritten (einem lesendem Teil und einem schreibendem) ausgeführt werden können.
• Benutzerabfragen sind zu Begin der Transaktion durchzuführen. Hierbei muss sichergestellt werden, dass möglicherweise zu diesem Zeitpunkt bereits schreibende Transaktionen geschlossen werden. (Natürlich nur, wenn bis dato noch keine Daten geschrieben worden sind.) Für den Fall, dass eine Transaktion vor einer Benutzerabfrage nicht geschlossen werden kann, ist das Makro G_AskYesNo o. ä. zu nutzen. Dieses Makro lässt dem Benutzer eine definierte Zeit für die Beantwortung der Abfrage. Die Transaktion wird abgebrochen, wenn diese Zeit verstreicht.
• Wird eine Transaktion durch ein Event (SELECT, DOUBLE_CLICK, ...) eines Widgets lesend durch "EndTXN BeginTXN(READ)" gestartet, so ist vorher zu überprüfen, ob die Message durch ein "SendMsg(..., DIRECT)" aus einer bestehenden Transaktion heraus ebenfalls getriggert wird.
• Eine Abbruch sollte immer mit einer verständlichen Fehlermeldung erfolgen. Dabei ist der Befehl Attention(AbortTXN) cancel zu verwenden. Der Parameter AbortTXN und der Befehl cancel lösen einen Rollback aus, so dass die Daten, die eventuell geändert wurden, wieder auf den Stand gesetzt werden, den sie vor der Transaktion hatten.
• Das Gültigkeitsdatum darf nur über die Message SET_VALIDITY_DATE geändert werden, ansonsten kann man bei einem Abbruch der Transaktion nicht den Status des Gültigkeitsdatum erkennen. Achtung, hier ist nicht die Gültigkeit von Objekten gemeint.

2.3 Programmiervorgaben

S. ausgewählte Programmbeispiele.

2.4 Tipps und Tricks

• Nach Möglichkeit 'vector | -> vector' durch 'vector Insert' ersetzen (z.B. bei garbageVector)

3. Dokumentation

Module müssen stets sofort beschrieben werden.

    3.1 Dokumentation im Modul

• Synopsis und Dictionary sollten die Funktion des Moduls ausreichend dokumentieren. Einer der Dictionary-Begriffe sollte auf den Geschäftsbereich verweisen für den das Modul im wesentlichen gedacht ist (z.B. Finanzbuchhaltung, Einkauf, etc.)
• Kommentare
  • werden in englischer Sprache erfasst
  • Makros müssen stets durch Kommentare ausreichend dokumentiert werden
  • Komplexe Programmbereiche sollten insbesondere dahingehend dokumentiert sein, warum das Programm die folgenden Codezeilen benötigt
  • "Gefährliche" Codestellen, d.h. Codebereiche, die auf keinen Fall oder nur unter größter Sorgfalt geändert werden dürfen, sollten spezifische Hinweise erhalten

    3.2 Dokumentation des Moduls in der Infothek

• Jedes Modul muss gemäß den Infothekrichtlinien dokumentiert werden. Neben einer genauen Beschreibung der Benutzerschnittstelle ist auch darauf zu achten, das Modul allgemein bezgl. seiner beabsichtigten Aufgabenerfüllung und in seinem Kontext zu anderen Modulen zu beschreiben. Entsprechende, gegenseitige Links sind zu erfassen.

4. Fehlerbehandlung

Können Fehler im Modul nicht behoben werden (z.B. wegen Fehlern in der Basis oder Datenbank), dann ist die folgende Kennzeichnung anzugeben:
// FIXME „Fehlernummer“ „Kürzel des Programmierers“ „Datum“

5. Weiterentwicklung

• Versionsänderungen sind beim Einchecken durch ausreichend deutsche Kommentare kenntlich zu machen

6. News

Auf dem ClassiX^® Intranet gibt es in den Bereichen Basis- und AppsWH - Entwicklung einen entsprechenden News-Link über den die neuesten Informationen erreichbar sind.

7. Fehlermeldungen

Treten in ClassiX^® Fehler auf, so können einige dieser Fehler sofort bestimmten Ursachen zugeordnet werden. Hier ist eine Liste mit bekannten Fehlern, ihren Ursachen und Lösungsansätzen.

8. Transaktionsbeschreibungen und Workflows

Transaktionsbeschreibungen und Workflows sind alle im Verzeichnis appswh\<branchname>\data\TXN-WF gespeichert und eingecheckt. Dies bedeutet, dass nach jeder Änderung die Transaktionsbeschreibung / der Workflow ausgecheckt, exportiert und wieder mit eingecheckt werden muss. So bekommt der Kunde bei einem Diff automatisch den letzten Stand mit ausgeliefert, egal wie viele Änderungen bis zum letzten Stand nötig waren. Es ist aufgrund der neuen Import Routine der Geschäftsprozesse nicht mehr notwendig, den Kunden die Änderungen an den Zuständen oder Übergangsbedingungen zu überlassen. Man kann einfach den exportierten Geschäftsprozess als Textdatei ausliefern, welchen der Kunde nur noch importieren muss.

Wichtig!
Bevor man etwas an einem Geschäftsprozess oder einer Transaktionsbeschreibung ändert, liest man diese vorher aus dem eingecheckten Stand ein! Sonst checkt man nachher noch seinen uralten angepassten Stand ein, was natürlich nicht geht! Übrigens, Transaktionsbeschreibungen muss man vor dem Importieren löschen!
Tip dazu:
Ist man  nicht sicher, ob der eingecheckte Stand wirklich aktueller ist, als der aus der Datenbank, die man gerade vom Kunden mitgebracht hat, so kann man einfach den entsprechenden Geschäftsprozess/Transaktionsbeschreibung auschecken, einmal exportieren und über Perforce's "Diff file against depot" vergleichen. Sind deutliche Unterschiede erkennbar, so ist zu klären, welcher der aktuellere Stand ist. Dieser sollte dann vor der eigentlichen Änderung eingecheckt werden, damit die Revisionshistorie nachher nur die wirklich geänderten Stellen markiert.

Und noch mal zur Erinnerung:
Transaktionsbeschreibungen werden mit der Endung .txn, Geschäftsprozesse mit der Endung .wfl exportiert.
Transaktionsbeschreibungen sind paarweise zu exportieren. (incl. rückgängig).
Es gibt ein paar Ausnahmen, bei denen man nicht so genau bestimmen kann, ob und wie sie zusammen gehören, (nicht mit der Kombination _BACK) bei denen bitte einmal in der eingecheckten Datei gucken, welche enthalten sind und auch genau so exportieren!

Richtlinien: 

>Wer Transaktionsbeschreibungen anfasst, der beschreibt diese bitte gleich nach folgendem Schema:

Sprich:

Im Kurztext wird beschrieben, um welche Änderungen es sich handelt.

In der Beschreibung wird dann die Vorbedingung in Worte gefasst, sodass man nicht jedes mal erst 'ne Viertelstunde analysieren muss, wann hier was wo passiert.

Dies ist noch ein ziemlich einfaches Beispiel, aber wenn es dann um komplexe Bedingungen geht, ist es eine wirkliche Vereinfachung.

Falls dies gegen eine vorher festgelegte aber unausgesprochene Richtlinie der Verwendung des Beschreibungsfeldes geht, bitte Info an mich. In diesem Fall könnten wir später die Beschreibung noch ergänzen, es ist aber trotzdem zwingend erforderlich, damit sofort anzufangen!