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.

Tipp

Mit dem Tastenkürzel: Strg + J kann ein "template for a structured program with GUI" aufgerufen werden.

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

CODE

//############################################################################## 
//############################################################################## 
// 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

CODE

//******************************************************************************
// 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

CODE

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

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

Beispiel

CODE

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

CODE

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

CODE

| 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

CODE

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

Zuweisungen

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

Beispiel

CODE

cMeineVariable := 1,

Mehrere Variablenzuweisungen nacheinander sollten wie folgt strukturiert werden:

CODE

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

CODE

//******************************************************************************|
// 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,