Lesbarkeit, Wartbarkeit

Themenpunkte:

Keine unbenutzten Deklarationen/Objekte oder unnützen Code

Ein Projekt sollte keine unausführbaren Pfade, keinen „Dead“ (unnötigen) Code und keine unbenutzten Typdeklarationen oder Variablen beinhalten.

Nicht verwendete Programmelemente führen in einem Projekt schnell zu unübersichtlichen Codestrukturen. Bei Wartungsarbeiten und Ergänzungen kann die Lesbarkeit des Codes stark erhöht werden, wenn das Projekt nur verwendete Programmelemente enthält.

Static Analysis:

Überprüfen mit Hilfe der folgenden Static Analysis Regeln:

Die Regel SA0033 ist auch in der lizenzfreien Variante Static Analysis Light enthalten.

Beachten Sie auch die Möglichkeit, Static Analysis Regeln und Namenskonventionen für überprüfte Stellen, an denen eine bestimmte Regel/Namenskonvention nicht mehr gemeldet werden soll, lokal per Pragma oder Attribut zu deaktivieren (siehe auch: Kapitel Pragmas und Attribute in TE1200 PLC Static Analysis). Eine lokale Deaktivierung kommentieren Sie optimalerweise mit entsprechender Begründung.

Beispielsweise können Sie die Regel SA0002 für beabsichtigt leere Rümpfe von Funktionsbausteinen lokal für diesen FB-Rumpf per {analysis -2} deaktivieren.

Keine unausführbaren Pfade

Negatives Beispiel:

IF FALSE THEN                   // NON COMPLIANT
    F_DoSomethingUsefulHere();  // will never be executed
END_IF

Positives Beispiel:

IF bTest THEN                   // COMPLIANT
    F_DoSomethingUsefulHere();  // it's just a sample
END_IF

Keinen „Dead“ (unnötigen) Code

Negatives Beispiel:

FUNCTION F_Sample_neg : INT
VAR_INPUT 
    nA       : INT;             // Variable a in term y = a*a + b
    nB       : INT;             // Variable b in term y = a*a + b
END_VAR
VAR
    nTemp    : INT;             // Used for temporary calculation of a*a
END_VAR

nTemp        := nA * nA;        // NON COMPLIANT: nTemp will not be used later
F_Sample_neg := nA * nA + nB;

Positives Beispiel:

FUNCTION F_Sample_pos : INT
VAR_INPUT 
    nA       : INT;             // Variable a in term y = a*a + b
    nB       : INT;             // Variable b in term y = a*a + b
END_VAR

F_Sample_pos := nA * nA + nB;   // COMPLIANT: no dead code in this sample

Keine „magischen Werte/magic numbers“

Verwenden Sie keine „magischen Werte/magic numbers“.

Bei Vergleichen oder Zuweisungen können alternativ Konstanten oder anderweitig fest definierte Werte genutzt werden. Auch Texte, wie Ausgabe- oder Vergleichstexte, sollten z. B. in Konstanten gespeichert und nicht direkt im Quelltext definiert werden.

Beachten Sie auch den folgenden Themenpunkt der Programmierkonventionen:

CASE-Anweisung nur mit Enumerationsinstanz

Negatives Beispiel:

PROGRAM Sample_neg 
VAR 
    nValue   : INT;   // Sample INT-variable that is used for comparison 
    bValueOk : BOOL;  // Indicates if the value of sample INT-variable is OK 
END_VAR

// NON COMPLIANT: A "magic value" is used for comparison 
bValueOk := (nValue = 125);

Positives Beispiel:

PROGRAM Sample_pos 
VAR 
    nValue    : INT;            // Sample INT-variable that is used for comparison 
    bValueOk  : BOOL;           // Indicates if the value of sample INT-variable is OK 
END_VAR 
VAR CONSTANT 
    cValueOk  : INT   := 125;   // Used to validate the sample INT-variable 
END_VAR

// COMPLIANT: A constant variable is used for comparison 
bValueOk := (nValue = cValueOk);

Kein mehrfaches Nutzen gleicher Namen

Vermeiden Sie das mehrfache Nutzen gleicher Namen. Dazu zählen folgende Fälle:

Der Name einer Enumerationskonstanten verglichen mit dem Namen einer Variablen
Die Namen von Objekten untereinander
Der Name eines Objekts verglichen mit dem Namen einer Variablen

Static Analysis:

Überprüfen mit Hilfe der folgenden Static Analysis Regeln:

Die Regel SA0027 ist auch in der lizenzfreien Variante Static Analysis Light enthalten.

Gleiche Notation in Deklaration und Implementierung

Aus Gründen der Einheitlichkeit sowie der Les- und Wartbarkeit sollten Sie in der Deklaration und in der Implementierung die gleiche Notation von Programmelementen und Variablen verwenden.

Static Analysis:

Überprüfen mit Hilfe von Static Analysis Regel:

SA0029: Notation in Implementierung und Deklaration unterschiedlich

Allgemeine Programmelemente für die folgenden Beispiele:

FUNCTION F_Sample

Negatives Beispiel:

PROGRAM Sample
VAR
    bTest  : BOOL;
END_VAR
--------------------------
IF btest THEN
    f_Sample();
END_IF

Positives Beispiel:

PROGRAM Sample
VAR
    bTest  : BOOL;
END_VAR
--------------------------
IF bTest THEN
    F_Sample();
END_IF

Leere Statements (;) vermeiden

Leere Statements (;)vermeiden, um den Code nicht unnötig auszudehnen. Falls ein leeres Statement zur Verdeutlichung eines bestimmten Falls unbedingt erforderlich sein sollte, sollte das leere Statement in einer eigenen Zeile stehen. Zusätzlich sollten Sie kommentieren, warum dieser Programmzweig leer ist.

Static Analysis:

Überprüfen mit Hilfe von Static Analysis Regel:

SA0003: Leere Anweisungen

Allgemeine Programmelemente für die folgenden Beispiele:

PROGRAM Sample
VAR
    nTest : INT := 10;  // Test value used in sample
END_VAR

Negatives Beispiel:

IF nTest = 10 THEN
    ;                   // NON COMPLIANT without a useful comment
ELSE
    nTest := 10;
END_IF

Positives Beispiel:

IF nTest = 10 THEN
    ;                   // COMPLIANT with a comment: In case that nTest is equal to 10, no action is needed. This status is intended.
ELSE
    nTest := 10;
END_IF

Jede Zuweisung in separater Codezeile

Jede Zuweisung sollte sich in einer separaten Codezeile befinden. Somit sollten sich keine Zuweisungen in Bedingungen befinden und Zuweisungsoperatoren sollten keine Unterausdrücke beinhalten.

Static Analysis:

Überprüfen mit Hilfe von Static Analysis Regel:

SA0095: Zuweisung in Bedingung

Allgemeine Programmelemente für die folgenden Beispiele:

PROGRAM Sample
VAR
    bVar1 : BOOL;
    bVar2 : BOOL;
    nA    : INT; 
    nB    : INT;
    nC    : INT;
END_VAR

Negatives Beispiel:

// NON COMPLIANT: assignment in condition
IF bVar1 := bVar2 THEN
    DoSomething();
END_IF
 
// NON COMPLIANT: more than one assignment in a single line
nA := nC * (nB := nC + nC);

Positives Beispiel:

IF bVar1 = bVar2 THEN
    DoSomething();
END_IF 
 
nB := nC + nC;
nA := nC * nB;