Codeblock Source Style Guide

Wichtige Styleguide-Informationen zur Formatierung von Codeblock-Programmen

Strukturierung eines Codeblock-Programms (siehe Beispiel)

Jedes Codeblock-Programm sollte wie folgt strukturiert werden:

• Beschreibung

• Variablen

• Konstanten

• Funktionen

• Eventhandler

• Actionhandler

• Oberflächen-Funktionen

• Hauptprogramm

Dies hilft bei der Erstellung von übersichtlichem Code und optimiert hierbei den Workflow.

Kommentare und Code-Trennung

Allgemein

Im Allgemeinen sollte jeder Code/Codeabschnitt der nicht trivial, also nicht sofort durchschaubar ist, mit kurzen klar verständlichen Kommentaren erklärt werden. Dies hat neben einer besseren Strukturierung den Zweck, dass spätere Änderungen am Code schneller durchgeführt werden können, da erheblich weniger Zeit benötigt wird um sich in den Code einzuarbeiten.

Kommentare

Neue Codebereiche werden mit einem Bereichskopf voneinander getrennt der, bis zur Markierung des rechten Seitenrandes im Editor reicht (80 Zeichen).

Beispiel

//############################################################################## 
//############################################################################## 
// Konstanten                                                                 
//############################################################################## 
//############################################################################## 
cMeineVariable := 1, 

Neue Funktionen werden mit einem Funktionskopf voneinander getrennt, der ebenfalls bis zur Markierung des rechten Seitenrandes im Editor reicht.

Dieser Sollte beinhalten

• (Mindestens ein vollständiger Satz. "Was macht diese Funktion?")

• Rückgabe. ("Was gibt diese Funktion zurück?")
  @Result: Typ - Beschreibung.
  @Result: null

• ("Benötigt es Externes handling oder kann es dies selbst?")
  @Transhandling: Extern
  @Transhandling: Intern
  @Transhandling: null

Beispiel

//******************************************************************************
// MeineFunktion fügt die Beiden Parameter zu einem String zusammen und
// gibt diesen zurück.                       
// @Result: Character - Zusammengesetzter Text aus nZahl und cText.
// @Transhandling: null
//******************************************************************************
function MeineFunktion(nZahl, cText)                                           
  result := Str(nZahl) + ' ' + cText,
end,                                                                            

Kommentare im Code die mehrere Zeilen betreffen sollten bündig mit dem darunterliegenden Code abschließen.

Beispiel

// Mein Kommentar
while not Bedingung do
  // Anweisungen
end,                                                             

Kommentare im Code die eine Zeile betreffen sollten hinter dem Code stehen.

Beispiel

cMeineVariable := 1, // Diese Variable = 1                                                  

Funktionslänge

• Eine Funktion sollte nie länger als 50 Zeilen sein! Nur in absoluten ausnahmen mehr.

Einrückungen

Einrückung immer drei Leerzeichen.

Beispiel

function BeispielFunktion()
  startseq,
    while Bedingung do
      if Bedingung then
        // Anweisungen...
      else
        // Anweisungen...
      endif,
    end,
  stopseq
end,                                               

Allgemeine Namensgebung

Namen für:

• Programme

• Funktionen

• Variablen

sollten wenn möglich einen sprechenden Namen erhalten. Hierbei ist darauf zu achten, dass der Anfang jedes Wortes/Abkürzung (bei Variablen nach dem Typenprefix) groß geschrieben wird.

Beispiel

• MeinNeuesProgramm

• function MeineNeueFunktion()

• m_cMeineNeueVariable,

Variablen

Prefixe

• Programmvariablen erhalten zusätzlich zu dem TypenPrefix das Prefix: m_
  Bsp.: m_cMeineVariable 

• TypenPrefixe:

  • numeric = n
    Bsp.: nMeineZahl

  • character = c
    Bsp.: cMeinText

  • boolean = b
    Bsp.: bMeinBoolean

  • datum = d
    Bsp.: dMeinDatum

  • objekt = o
    Bsp.: oMeinObjekt

Ausnahmen

• Variablen für For-Schleifen etc. erhalten kein Prefix.

Beispiel

| i, j, k, l, m, n |
for i := 0 to m_nKonstanterWert do
  // Anweisungen...
end,                       

Abstände und Trennung

• Variablen werden immer mit mit einem "," und einem darauf folgenden Leerzeichen voneinander getrennt.

Beispiel

| nMeineZahl, cMeinText |
function MeineFunktion(cParameter1,nParameter2)...

Zuweisungen

Eine Variablenzuweisung ist immer durch Leerzeichen von dem Operanden und dem Wert zu Trennen.

Beispiel

cMeineVariable := 1,

Mehrere Variablenzuweisungen nacheinander sollten wie folgt strukturiert werden:

cMeinText    := "text",
oMeinBoolean := true,
nMeineZahl   := 1,

Die Operanden (z. B. :=, +=... ) werden hierbei dem längsten Ausdruck angepasst.

Events und Actions

Wenn Code in einer Event- oder Action-Funktion länger als ein paar Zeilen ist sollte eine neue Funktion erstellt werden, die die Logik beinhaltet. Das Event oder die Action soll dann nur noch diese Funktion aufrufen.

Beispiel

//******************************************************************************|
// Logik die durch Aktion angestoßen wird
// @Result: null
// @Transhandling: null
//******************************************************************************|
function MeineLogik()
   // nicht trivialer längerer Code
end,

//******************************************************************************|
// Meine Aktion beim Klicken auf den Button
// @Result: null
// @Transhandling: null
//******************************************************************************|
function A_MeineActionExecute(Sender)
   MeineLogik(),
end,