GDL Standards

GDL Standards

Zuletzt geändert: 23. Februar 2021
Du bist hier:
Geschätzte Lesezeit: 7 min

Dieser Artikel beschreibt die Definition und Nutzung von GDL-Standards bei b-prisma.

Einführung

Diese Dokumentation enthält Technische Standards und Designvorgaben, welche bei der GDL-Programmierung von ArchiCAD-Bibliothekselementen (GDL-Objekten), welche bei b-prisma erstellt werden, einzuhalten sind.
Außerdem werden einige Regeln und Empfehlungen beschrieben, die nicht zwingend einzuhalten sind, aber empfohlen werden. Sämtliche Standards, Regeln, Empfehlungen, Vorgaben, die NICHT verbindlich sind, sondern nur empfehlenden Charakter haben, sind durch Kursivschrift gekennzeichnet.

Diese Dokumentation wurde erstellt, um einen einheitliche Standard beim Scripting zu gewährleisten, damit alle beteiligten GDL-Programmierer und andere Projektbeteiligte immer auf den selben Standard zugreifen können und sich sofort zurechtfinden.
Im übrigen wird empfohlen, sich an die Graphisoft-Dokumenatationen „Library Design“, „Library Specification“, „GDL-Style-Guide“ und „GDL Advanced Technical Standards“ zu halten, soweit diese nichts anders sagen, als die b-prisma-Standards.

Namensgebung

Im Laufe der Jahre hat sich eine Namensgebung bei b-prisma etabliert, die sich zum Teil an Graphisoft-Vorgaben hält, zum Teil aber bewusst davon abweicht.
Die Art der Namensgebung und

Groß/Kleinschreibung verfolgt den Zweck, dass ein Maximum an Übersichtlichkeit und Verständnis der Scripte und Parameter- und Variablennamen gegeben ist.

Grundsätzliches

  • sämtliche Befehle und Globalen Variablen werden komplett in Großbuchstaben geschrieben, damit sie sich von Parametern und Variablen unterscheiden
  • sämtlich Parameternamen und Variablennamen werden entweder gemischt klein/GROSS geschrieben oder klein; komplette Großschreibung ist nicht erlaubt
  • sämtliche Objekte sind mit dem Namen des Entwicklers zu versehen und mit dem Datum der letzten Änderung, ggf. einer Versionsnummer

Parameter

  • Alle Parameter fangen mit einem kleinen Bezeichner, der den Parametertyp kennzeichnet, an gefolgt von einem Unterstrich, gegliedert von allgemein zu spezifisch.
  • der 2. Teil beginnt mit einem Großbuchstaben und beschreibt die Funktion
  • der 3. Teil beginnt mit einem Großbuchstaben und beschreibt das Bauteil
  • Beispiel: str_TypFenster (nicht FensterTyp), erlaubt ist auch str_Typ_Fenster

Parametertypen

Zur Unterscheidung der Parametertypen im Script erhalten diese folgend aufgeführten Präfixe gefolgt von Unterstrich und Bezeichnung wie oben.

  • Länge: x_Parameter, y_Parameter, z_Parameter
  • Winkel: ang_Parameter
  • Gleitkommazahl: real_Parameter
  • Ganzzahl: int_Parameter
  • Boolescher Wert: b_Parameter
  • String: str_Parameter
  • Schraffur: fill_Parameter
  • Material: mat_Parameter
  • Stift: pen_Parameter
  • Linientyp: line_Parameter

Variablen

  • alle im Script definierten Variablen fangen mit einem Unterstrich an
  • der erste Teil beginnt klein und beschreibt die Funktion, der zweite Teil beginnt mit einem Großbuchstaben und beschreibt das Bauteil
  • Beispiel: _langProfil
  • Abweichungen: eps = 0.0001 und htsp = 0 (Vergleichsvariable und Hotspothochzähler)
  • Variablen, die nur in einer Subroutine vorkommen, beginnen mit 2 Unterstrichen, z.B.: __iTuerTyp; alternativ ist auch erlaubt ~typTuer, erlaubt ist auch _lang_Profil
  • Schleifenzähler: als Schleifenzähler kommen NUR Kleinbuchstaben ohne Zahlen und Unterstriche in Frage; man startet immer mit i, gefolgt von j, k, m und n. l sollte man vermeiden, da es schlecht von I und 1 zu unterscheiden ist. Bei Schleifen in Subroutinen sind grundsätzlich Doppelbuchstaben wie ii, jj, kk zu verwenden oder i_1, i_2, etc.

Stile

Folgende Zeichenstile sind ebenfalls einzuhalten. Leerzeichen bedeuten zwar ein gewissen Mehraufwand beim Scripten, erhöhen jedoch die Scriptübersichtlichkeit und damit die Lesbarkeit erheblich. Gleiches gilt für Abschnittsbegrenzungen.

  • Vor und nach = steht immer ein Leerzeichen, sowie bei Rechenoperanden
  • Falsch: IF i=1 THEN h[n + 6]=h+5 | j = – x | not (x)
  • Richtig: IF i = 1 THEN h[n+6] = h + 5 | j = -x | not(x) | s = MIN (a, 25 * b, c)
  • Keine Leerzeichen sind erlaubt vor und hinter den folgenden Operatoren: Indizierung von Arrays: array[25] logisches „not“: not(x) unäres minus, unäres plus: -x, +x
  • Codeabschnitte und Abschnittsbegrenzer bitte wie folgt verwenden: Überschrift in Bindestrichzeilen eingefasst, Leerzeilen über und unter Bindestrichzeilen, Abschnittsbegrenzungstext in G R O S S B U C H S T A B E N mit Leerzeichen dazwischen, was die Übersichtlichkeit weiter erhöht, dann Name des Codeblocks mit >> am Anfang und Name des Codeblocks mit << am Ende:

! ---------------------------------------------------------------------- ! !ABSCHNITTSBEGRENZUNG
! ---------------------------------------------------------------------- ! !------CODEBLOCK 001--->>
!Hier steht der Codeblock! 
!<<---CODEBLOCK 001---

Scriptüberschriften

Jedes Script soll eine Überschrift erhalten, damit es in der XML-Version des Objektes besser unterschieden werden kann.

! ---------------------------------------------------------------------- !
! -------- M A S T E R - S c r i p t --------------------------- !
! ---------------------------------------------------------------------- !

END-Zeilen sind wie folgt anzulegen:

! ---------------------- E N D -------------------- !
! ---------------------- E N D -------------------- !

END ! END ! END ! END ! END ! END ! END

! ---------------------- E N D -------------------- !
! ---------------------- E N D ---------------------!



Subroutinen sind durch Doppel-Bindestrichzeilen voneinander zu trennen. Der Name der Subroutine kann eine Zahl sein oder ein Text in Anführungszeichen. Dahinter ist immer die Funktion der Subroutine anzugeben. Bei komplexeren Subroutinen empfiehlt es sich, eine kurze Beschreibung, sowie die übergebenden und zurückgegebene Variablen aufzuführen.

! ---------------------------------- !
! ---------------------------------- !
! Erzeugt ein 3D-Türband, 
! der bewegliche Teil folgt 
! in Subroutine 101
! übergebene Parameter
! _durchmesserBand
! _materialBand
! Rückgabewerte
! keine
! ---------------------------------- !

100: ! ------ T Ü R B A N D -------- !
    ! Subroutinencode ist eingerückt
RETURN
! ---------------------------------- !
! ---------------------------------- !

Dokumentation im Script

Jeder Scriptteil ist innerhalb des Scripts durch Kommentare zu dokumentieren. Es ist anzugeben, WAS der Scriptteil macht, WIE er es macht, ggf. WARUM etwas gemacht wird, WO es Verknüpfungen von und zu diesem Scriptteil gibt.

Denke immer daran, dass Du in 10 Jahren noch erkenn musst, was Du Dir heute dabei gedacht hast.

Einrückungen (Tab-Sprünge)

Bei Kontrollfluss-Anweisungen, Schleifen, sind Tabsprünge, ggf. gestaffelt, zu verwenden.
Beispiele:

FOR i = 1 TO anz
    ADDx (i - 1) * A
    ! Codeblock
    DEL 1
NEXT i


IF strTypTuer = „Schwingtür“ THEN
    ! Codeblock
ENDIF


ADDx 1
ROTy 44
    ! Codeblock
DEL 2

Halbfertige Arbeiten (todos)

Bei nicht fertigen Codebereichen soll immer das Schlüsselwort TODO als Erinnerung gesetzt werden. So ist es einfacher, die Stelle wiederzufnden, z.B.:

ADDx 1 ! TODO: temporäre Verschiebung; später wieder aufheben
! Codebereich
DEL 1

Markieren von zusammenhängenden Befehlen

Bei längeren Scriptbereichen sollen zusammenhängende Befehle entsprechend kommentiert werden, z.B. bei Koordinatentransformationen und Bedingungs-Abläufen, z.B.:

ADDx _verschiebungRahmen ! ko-trafo 01
If Bedingung_1 THEN
    IF Bedingung_2 THEN 
        ! Größerer Codebereich
    ENDIF ! Bedingung_2
ENDIF ! Bedingung_1
DEL 1 ! ko-trafo 01

Parameter-Script

Festsetzungen von Parametern
Will man den Wert eines Parameters unter Verwendung des Befehls PARAMETERS im Parameter-Script ändern, muss eine ähnliche Festsetzung im Master-Script erfolgen. Dies sorgt für eine korrekte Anzeige des Objektes für Fälle, wenn das Parameter-Script nicht vom System durchlaufen wird. z.B.:

! Parameter-Script
if Bedingung_1 then
    str_TypFenster = „Holzfenster“
    PARAMETERS str_TypFenster = str_TypFenster
endif
! Master-Script
if Bedingung_1 then 
    str_TypFenster = „Holzfenster“
endif

3D-Script

3D-Darstellung: unbedingt alles im 3D-Kontext weglassen, was nicht sichtbar ist, aber eine hohe Polygonanzahl besitzt und somit Rechenleistung fordert.
Es gibt bestimmte Elemente, die nur im Schnitt sinnvoll sind, nicht jedoch in 3D.

Fehlerkontrolle

In viel verwendeten Bibliothekselementen sollten möglichst umfassende Fehlerkontrollen eingebaut werden, welche verhindern, dass bei Eingabe ungültiger Parameterwerte durch den Anwender keine Fehlermeldungen auftauchen oder sogar das Objekt nicht mehr angezeigt wird:
Einige Beispiele für Fehlerkontrollen:

! — PEN darf nicht kleiner als 1 in 2D sein
IF post_fill_pen < 1 THEN post_fill_pen = 1

! — prüfe, ob die „Misch-Schraffur 50 %“ existiert, dann ist rrr = 1
fill50 = IND(FILL,“Misch-Schraffur 50 %“)
framefill = fill50
rrr = REQUEST(„Name_of_Fill“, framefill, fillName)

HOTSPOTS

Sämtliche Hotspots sind mit einer ID zu versehen, auch die nicht beweglichen, damit bei Vermassungen diese dynamische bleiben; bei Hotspots ohne IDs kann es passieren, dass sich die Bemaßungen bei Änderungen der Objektgröße nicht dynamisch anpassen.
Es ist für jedes Objekt samt Makros und Submakros eine Dokumentation über die Verwendung der Hotspot-IDs anzulegen, damit sichergestellt ist, dass es in unterschiedlichen Skripten nicht identische Hotspot-IDs gibt.
Z.B. Hauptobjekt 3D. 1 – 99, Hauptobjekt 2D: 100 – 199
Makro 3D: 1001 – 1099, Makro 2D: 1100 – 1199
Alternativ kann bei Makros auch die ID per Übergabe durchgezählt und per Returned Parameters ins Hauptobjekt zurückgespielt werden, wo dann weitergezählt wird.
In sämtlichen Skripten ist ausschließlich ein einziger identischer Variablenname für das hochzählen von Hotspots einzusetzen. Diese Variable braucht abweichend nicht mit einem Unterstrich zu beginnen.
z.B.: htsp = 1
HOTSPOT2 A, B, htsp : htsp = htsp + 1

MEHRSPRACHIGKEIT

Bei Aufträgen für international tätige Firmen sind immer von Anfang an die Grundlagen für eine Mehrsprachigkeit zu legen.
Folgende Dinge sind dabei zu beachten:
Anlegen eines Auswahlparameters für die Mehrsprachigkeit: int_language (1 = de, 2 = en, etc.)
Anlegen eines Makros für alle Sprachen oder je eines Makros für eine Sprache (Script abschließen mit END _durchgangsbreite, _durchgangshoehe etc. bzw. einfach mit END _translation)
Definition der Sprachpaare entweder als bekannte Variable oder als hochgezählte Arrayvariable, z.B.:
_durchgangsbreite = „durchgangsbreite“ (IF int_language = 1)
_durchgangsbreite = „egress width“ (IF int_language = 2)
_translation[int_language][1] = „durchgangsbreite“ (IF int_language = 1)
_translation[int_language][1] = „egress width“ (IF int_language = 2)Vorteile von Variante 1 ist die bessere Lesbarkeit beim Einsetzen der Variablen, Nachteil das wesentlich aufwändigere Script, da man in den Makros und in den CALL-Befehlen die einzelnen RETURNED_PARAMETERS einsetzen muss (Beispiel siehe unten)Vorteile von Variante 2 ist das einfacher zu erzeugende Script und die kürzeren Makro-Befehle, Nachteil die ziemlich schlechte Lesbarkeit beim Einsetzen der Variablen
Makroaufruf in etwa wie folgt:
a) Variablenverwendung:CALL „translation_object.gsm“ PARAMETERS RETURNED_PARAMETERS _durchgangsbreite, _durchgangshoehe etc.
b) Arrayverwendung:CALL „translation_object.gsm“ PARAMETERS RETURNED_PARAMETERS _translation
Bei vielen Werten sind die Wörter nach Themen bzw. inhaltlicher Bedeutung zu sortieren und zu kennzeichnen (z.B. UI-Texte, VALUES-Werte, etc.)

Spezifizierung (aus: Graphisofts® Library Specification)

Erste Voraussetzung bei der Erstellung eines GDL-Objektes ist, dass sein Zweck und seine Funktion klar definiert sind, um einen perfekten Überblick über die Funktion des Objektes zu bekommen: den Abstraktionsgrad, die Eigenschaften, 2D- und 3D-Darstellung, sowie die Darstellung in Schnitten und Ansichten. Eine der grundlegenden Fragen lautet: wozu soll das Objekt verwendet werden?
Hieraus werden vom GDL-Entwickler in Abstimmung mit dem Auftraggeber sämtliche Parameter und ihre hierarchische Struktur definiert. Die Logik der Parametrik muss sich in der Anordnung der Paarmeter widerspiegeln; die Parameter sollten in Gruppen angeordnet werden und die Verknüpfungen von Parametern untereinander muss klar definiert werden (und später im Parameter-Scipt ausgearbeitet werden). Um dies sicherzustellen, müssen Verbindungen von Parametern untereinander genauestens analysiert werden.
Vom Auftraggeber müssen Spezifizierungs-Zeichnungen erstellt werden, bevor mit der Erstellung eines neuen Bibliothekselementes begonnen wird. Spezifizierungs-Zeichnungen müssen jede Darstellungsvariante jedes Einzelobjektes – wie folgt beschrieben – enthalten:
diese müssen in unterschiedlichen Maßstäben gezeichnet sein, falls 2D und 3D ihre Darstellung in Abhängigkeit vom Maßstab ändern sollen
unabhängige Versionen müssen für Fenster/Türen gezeichnet werden, einmal mit und einmal ohne Zusatzelemente, wie Seitenlichter, Oberlichter, Riegel, Pfosten, Kämpfer, Wandanschlüsse etc.
diese sollten Grundrisssymbol, Schnitt- und Ansichtssymbole in durchgängig einheitlicher Darstellungsart enthalten
Sämtliche durch Parameter veränderlichen Werte sind mit einheitlichen Buchstaben (Grundriss, Schnitt, Ansicht) in Maßketten zu kennzeichnen; sämtliche Fixgrößen sind durch Zahlenwerte zu kennzeichnen
Der Programmierer sollte auch für Fixgrößen später im Script Variablen verwenden, um spätere Änderungen zu vereinfachen. Um unerwartete Probleme zu vermeiden, sollte für sämtliche Attribute (Stift oder Schraffur) ein zusätzlicher oder interner Parameter verwendet werden, den man von einer zur anderen Version leicht ändern kann.
Die Zeichnungen müssen das Modell in jedem Fall so zeigen, wie es hinterher aussehen soll. Um Missverständnisse zu vermeiden, können keine Skizzen akzeptiert werden, die weniger detailliert sind als das gewünschte Ergebnis.
Die Spezifizierungs-Zeichnungen müssen alles enthalten, das für den Auftraggeber wichtig ist. Der Programmierer kann Dinge, die nicht in den Spezifizierungs-Zeichnungen gezeigt werden, auch nicht mit in das Objekt einbauen.
Das Entscheidende ist eine gute Kommunikation zwischen Auftraggeber und Programmierer.Dies ist u.a. auch dafür wichtig, damit nicht schwerwiegende Änderungen in einer fortgeschrittenen Phase der Objekt-Entwicklung notwendig werden.

Prototypen (aus: Graphisofts®Library Specification)

Normalerweise ist es unmöglich, eine klare Spezifizierung für eine bisher noch nicht vorhandene Funktionalität im Voraus aufzustellen. Prototypen sind daher eine gute Lösung für Auftraggeber und Programmierer, um die Anforderungen und Spezifizierungen untereinander zu kommunizieren. Um die Anforderungen und deren mögliche Lösungen in einer fortgeschrittenen Form darzustellen, sollten ein Prototyp-Objekt für ein Objekt bzw. für grundlegende Objekttypen einer Bibliothek erzeugt werden.
Prototypen müssen vom Auftraggeber sehr genau geprüft werden. Sie sollten sämtliche Parameter, Optionen und Eigenschaften des fertigen Bibliothekselementes enthalten. Sehr oft ist dies in einer frühen Phase der Entwicklung nicht möglich, so dass Bibliothekselemente so vorzubereiten sind, dass Modifikationen leicht möglich sind. Aus diesem Grund sollte ein Bibliothekselement niemals als die ultimative Lösung für die Anforderungen des Auftraggebers in Betracht gezogen werden.

Qualitätsmanagement

Je umfangreicher ein Projekt oder Objekt ist, desto wichtiger ist ein umfassendes Qualitätsmanagement zur Erzielung eines gleichmäßig hohen Qualitätsstandards und zur Beseitigung von unvermeidlichen Bugs.
Qualitätssicherung ist nicht das letzte Glied der Entwicklungskette, es ist ein Schritt im fortlaufenden Prozess der agilen Softwareentwicklung. Testing findet in jeder Entwicklungsphase statt. Entsprechend muss Software-Testing als ein regelmäßiger und fortlaufender Entwicklungsschritt in den alltäglichen Entwicklungsprozess integriert werden.
Wichtige Teile des Qualitätsmanagements sind das Vorgeben von Standards, eine Checkliste zum Abarbeiten von Standards, die Überprüfung der Einhaltung der Standards, eine sorgfältige nachvollziehbare Dokumentation des Entwicklungsprozesses mit Dokumentationstemplates, ein ausführlicher Betatest mit Bugreporting und Bugfixing.
Elemente eines Standard-Betatests:
Standardfragenkatalog: Geometrie
Standardfragenkatalog: Logik
Standardfragenkatalog: User Interface
Standard: Sind Fehleingaben ausgeschlossen?
Projektfragenkatalog: Produktlogik, wurden die Vorgaben umgesetzt?
Testen in unterschiedlichen Umgebungen: 2D, 3D, Schnitt, Ansicht, Rendering, Hotspot-Editing, Listenauswertung, Geschosse, Modelldarstellungen
Tests auf Windows und MAC

Tags:
War dieser Artikel hilfreich?
Mag ich nicht 0 0 of 0 fanden diesen Artikel hilfreich.
Anzahl Aufrufe: 130

Schreibe einen Kommentar

Close Menu