Styleguide NAVISION Programmierung. Inhaltsverzeichnis

Transkript

1 Wir haben eigene Richtlinien, wie der Quell-Code in NAVISION aussehen soll. Dies sind keine Erfindungen von Menschen, die sonst nicht zu tun haben, sondern Ergebnisse langjähriger Projekterfahrungen, die zeigen, dass ohne Regeln der Quellcode in grossen Projekten schnell unwartbar wird. Für die Programmierung in NAVISION gilt der NAVISION C/AL Styleguide. Dieser Styleguide wird in einigen Bereichen ergänzt, um die Lesbarkeit und die Qualität des Quellcodes zu erhöhen. Inhaltsverzeichnis Styleguide...2 Grundlagen...2 Codierungsstandard...2 Variablenbezeichner...2 Scope...3 Type...3 Implizite Variablen...5 Textkonstanten...5 Strukturen...5 Funktionen und Prozeduren...5 Weitere Richtlinien...5 Dokumentation...6 Dokumentation im Projekt...6 Documentation Tag...6 Quell-Code...7 Auskommentieren von NAVISION Standard Quellcode...7 Kurzkommentare...7 Mehrere Programmzeilen...7 Dokumentation von Funktionen und Prozeduren...8 Sonstige Hinweise...9 Tabellenfelder...9 Primärschlüssel...9 Custom Fields...9 Reports...9 Formatierung Quellcode...9 Kremer & Thimm GmbH Rev. 7 Seite 1 von 10

2 Styleguide Grundlagen Der hier vorgestellte Styleguide fasst die Erfahrungen aus verschiedenen Projekten zusammen. So wurde in einem grossen Projekt der "Hochtief Software GmbH" sehr auf die Variablenbezeichnung geachtet, so dass es sinnvoll erschien, einen eigenen Styleguide zu erstellen. Codierungsstandard Ein Codierungsstandard ist eine Menge von Regeln, deren Einhaltung dafür sorgen soll, dass Programmcode les- und wartbar bleibt. Das gilt besonders: sobald mehr als eine Person denselben Code bearbeiten soll bei Programmen, die zwar nur von einer Person geschrieben werden, aber irgendwann einmal von jemandem anderen gewartet werden sollen wenn man ein Programm auch ein paar Wochen, nachdem man es geschrieben hat, noch selber verstehen möchte "Den Einen" Codierungsstandard gibt es nicht - es ist daher oft erforderlich, sich an einen anderen, oft schon von außen vorgegebenen Standard anzupassen. Wenn wir in einem Projekt arbeiten, verwenden wir unseren Styleguide, es sei denn, im Projekt ist ein Codingstandard vorgegeben (schwache Codierungsstandards werden i. d. R. durch unseren Styleguide erweitert, sofern unsere Regeln nicht die Les- und Wartbarkeit verschlechtern. ) Variablenbezeichner Die Variablenbezeichner enthalten Hinweise auf die Reichweite (Scope) und den Typ der verwendeten Variablen. Hierdurch ist beim Lesen des Quelltextes ersichtlich, um welchen Typ es sich handelt. Programmierer, die Erfahrungen in anderen Programmiersprachen haben (JAVA, C++, Python,...) kennen dieses Konzept und nutzen dies auch in der Regel. Nur in NAVISION wird dies nicht oder nur selten verwendet. Wir lehnen uns an die sog. "Hungarian Notation" an. Bei der Hungarian Notation handelt es sich um eine von einem Ungarn, nämlich Charles Simonyi, entwickelte Namenskonvention, die vor allem im Zusammenhang mit C und Microsoft Windows verwendet wird. Wir beziehen uns dabei auf die "Systems Hungarian Notation" (also eigentlich die Fehlinterprettion, aber dennoch eine sinnvolles etabliertes Konzept). Kremer & Thimm GmbH Rev. 7 Seite 2 von 10

3 Reichweite und Typ werden in Kleinbuchstaben beschrieben, der eigentliche Variablenname beginnt mit einem Grossbuchstaben. Die Position der ergänzenden Hinweise zum Type und des Scopes hängen von der Entscheidung ab, ob mit einem Prefix oder Suffix gearbeitet wird. In NAVISION bietet sich die Verwendung des Suffix an, da die Suche der Variablen auf den Anfangsbuchstaben beschränkt ist. Enthält nun der Anfangsbuchstabe den Scope, dann ist die Variablensuche sehr langwierig. Dennoch haben wir in den Projekten weiterhin das Prefix verwendet, da es leichter zugänglich ist. Scope Der erste Buchstabe beschreibt die Reichweite der Variablen. Der Buchstabe orientiert sich dabei weitestgehend an den in NAVISION verwendeten Begriffen. g l p v r Bedeutung Globale Variable lokale Variable Konstanter Parameter bei Funktionsdeklarationen variabler Parameter bei Funktionsdeklarationen Rückgabe Wert bei Funktionsdeklarationen Type Die zweiten bzw. dritten Buchstaben bezeichnen den Typ der Variablen: Anfangsbuchstabe Anfangsbuchstabe i t c d o b da ti dt bn Type Integer Text Code Decimal Option Boolean Date Time DateTime Binary Kremer & Thimm GmbH Rev. 7 Seite 3 von 10

4 Anfangsbuchstabe bl df tf bi du gu fi tt oc au is os v di ac r rt oder rtemp rr ri fr kr cu fm rp dp xp ms ch Type BLOB DateFormula TableFilter BigInteger Duration GUID File TransactionType OCX Automation InStream OutStream Variant Dialog Action Record temporärer Record RecordRef RecordID FieldRef KeyRef CodeUnit Form Report Dataport XML Port Menu Suite Char Diese Liste erscheint sehr umfangreich, aber im Tagesgeschäft werden i. d. R. lediglich die einfachen und direkt nahe liegenden Prefixe verwendet, Kremer & Thimm GmbH Rev. 7 Seite 4 von 10

5 Implizite Variablen Die Bezeichner i, j, k, l, m, n können als Laufvariablen vom Typ Integer verwendet werden, sofern sie als lokale Variablen deklariert sind. Ebenso kann der Bezeichner c für einzelne Zeichen verwendet werden, sofern er als lokale Variable deklariert ist. Textkonstanten Im NAVISION Standard werden Textkonstanten immer mit einer laufenden Nummer aufgeführt. Dies trägt zur Lesbarkeit des Quellcodes in keiner Weise bei. Daher werden zur besseren Lesbarkeit Textkonstanten mit einem sinnvollen Namen bezeichnet und generell in Grossbuchstaben geschrieben 1. NO_CUST_1 Der Debitor \%1 existiert nicht. Textkonstanten sind global zu definieren. Die Anzahl der notwendigen Parameter ist am Ende des Konstantenbezeichners, durch einen Unterstrich getrennt, anzugeben. Strukturen Die Kontrollstrukturen IF, FOR, etc. haben generell BEGIN/END Blöcke zu enthalten. Die Vereinfachungsregel, dass bei nur einer Folgezeile auf die Blockmarkierung verzichtet werden darf, gilt nicht. Funktionen und Prozeduren Generell gilt für Funktionen dieselbe Bezeichnungssystematik, wie für die Variablen. Funktionen beginnen generell mit einem "f" und der Rückgabewert bestimmt die darauf folgenden Buchstaben. Hat eine Funktion keinen Rückgabewert, so schließt sich der Funktionsname direkt an das "f" an. Weitere Richtlinien Lokale Funktionen beginnen mit einem "l" statt mit einem "f". 1 Wer aus der C-Programmierung kommt, wird sich an die gross geschriebenen Konstanten erinnern. Kremer & Thimm GmbH Rev. 7 Seite 5 von 10

6 Funktionen ohne Parameter werden mit einem leeren Klammerpaar aufgerufen: ftgetos() Funktionen in Tabellenobjekten sind nur dann erlaubt, wenn die Funktion auf den instantiierten Record zugreift. Allgemeingültige Funktionen, die als Parameter einen Record vom Typ des Tabellenobjekts enthalten, müssen in Codeunits abgebildet werden. Die Ursache liegt in der impliziten Verwendung des instantiierten Records. Die ID einer Funktion muss auf den Custom Nummernkreis gesetzt werden: Validierungen und Routinen zum Insert/Modify/Delete etc. sind in Tabellenobjekten abzubilden. Nur in absoluten Ausnahmefällen dürfen diese Anpassungen in Forms aufgenommen werden. Auf Programmierungen in Forms ist innerhalb der Dokumentation deutlich hinzuweisen. Dokumentation Neben der externen Anwender-Dokumentation wird im Quellcode ausführlich dokumentiert, wann, wer, was und warum geändert hat. Im Rahmen der Release- Erstellung können die Änderungs-Kommentare weitestgehend wieder entfernt werden. Dokumentationen projektspezifischer Anpassungen bleiben generell erhalten. Dokumentation im Projekt // Dies ist ein Kommentar Documentation Tag Im Kopf wird aufgeführt, welche Anpassungen durchgeführt wurden. Hierbei stehen die letzten Änderungen am Anfang der Liste! hth Korrektur Zugriff auf die Tabelle... jkr Neues Feld... Wurden durch einen Entwickler mehrere Änderungen durchgeführt, so sind zusätzlich laufende Nummern anzufügen. also z. B. hth Korrektur Zugriff auf die Tabelle... hth Erweiterung Feldlänge jkr Neues Feld Kremer & Thimm GmbH Rev. 7 Seite 6 von 10

7 Erfolgen Änderungen auf Grund von Tickets in unserem Ticketsystem, so sollte mindestens die Ticketnummer aufgeführt werden. Ideal wäre die Angabe des direkten Pfades zum Ticket, also z. B. Quell-Code Im Quellcode erfolgt dann an den betroffenen Stellen der Hinweis auf die Änderungen. Hierbei ist zu beachten, dass Zeilen aus dem Originalcode nicht gelöscht werden, sondern lediglich auskommentiert werden! Auskommentieren von NAVISION Standard Quellcode // << grcust.get("customer No."); Kurzkommentare Wurde die Anpassung nur in einer Zeile durchgeführt, so wird der Verweis auf den Kommentar an das Ende der Zeile geschrieben: grcust.get("customer No."); // hth Besser ist es jedoch, wenn man auch hier den Kommentar als Block darstellt. Mehrere Programmzeilen Sind mehrere Programmzeilen betroffen, so werden die Änderungen in einen Kommentarblock eingeschlossen: // hth b // << grcust.get("customer No."); IF grcust.get("customer No.") THEN BEGIN END; // hth e Die Benutzung von geschweiften Klammern zum Auskommentieren ist soweit wie möglich zu vermeiden. Kremer & Thimm GmbH Rev. 7 Seite 7 von 10

8 Dokumentation von Funktionen und Prozeduren Soweit wie möglich sollte jeder Funktionsdeklaration ein Dokumentationsheader folgen, der die Aufgabe der Funktion und die Parameter Dokumentiert. [ffootest(var...)] = Trigger in NAVISION // Aufgabe der Funktion: Ermittlung der... // Parameter : v vrdata, Record, 4711 Hilfstabelle... // pdperiod Analyseperiode // // Rückgabe : keine // Globale Var : keine Verwendung von globalen Variablen // // Hinweise zur Verwendung // Kremer & Thimm GmbH Rev. 7 Seite 8 von 10

9 Sonstige Hinweise Tabellenfelder Primärschlüssel Die Felder, die zum Primärschlüssel zählen, werden mit den Field Ids 1 bis 9 belegt. Custom Fields Zur besseren Übersicht sollten Field Ids verwendet werden, die logisch gruppiert werden können. Auf diese Weise findet man zusammenhängende Felder in einem logischen Block und muss nicht über die gesamte Tabelle recherchieren. Reports Berichten in NAVISION haben standardmässig keinen Hinweis darauf, welcher Bericht ausgeführt wird. Alle Berichte, die durch die uns erstellt werden, sollten folgende Hinweise haben (natürlich nicht bei Belegen wie Rechnungen, etc.): Bericht: Version: Hier wird die deutsche CAPTION des Report-Objekts ausgewiesen, wenn nicht vorhanden, dann wird der Name des Report-Objekts ausgewiesen. Es wird die Version des Report-Objekts ausgewiesen Zusätzlich gibt es eine interne Versionsnummer, z. B. wenn die Lösungen über das SVN mit Versionsnummern eingechecked wurden. Hierzu ist eine Funktion zu verwenden, die die Version des Objekts zurückgibt. Die Version ist lediglich vom Typ Integer, ohne weitere Informationen. Formatierung Quellcode Es gibt immer wieder lästige Angewohnheiten, die das Lesen des Quellcodes erschweren oder andere Probleme verursachen. Nach einer geöffneten Klammer und vor einer schließenden Klammer kommt kein Leerzeichen: falsch:( 3 + i ) richtig: (3 + i) Im Quellcode ist eine Leerzeile nach logischen Blöcken einzufügen. Kremer & Thimm GmbH Rev. 7 Seite 9 von 10

10 DateFormula generell in englisch: CALCDATE('<-CM>', WORKDATE()) statt CALCDATE('-LM', WORKDATE()) Kremer & Thimm GmbH Rev. 7 Seite 10 von 10