Beispiel für gut kommentierten Deklarationskopf

[radar17892]

Hallo ihr Schreibfaulen da draussen,
immer wieder bekomme ich diverse Programme oder Teile zu sehen, die zwar programmiertechnisch gut gelöst sind, aber leider mit einem Minimum an Kommentar.
Wie soll man da die Gedanken des Schreibers nachvollziehen?? Oder dieser selbst, nach ein paar Jahren!
Ich persönlich bin der Meinung: die Hälfte der Programmierarbeit ist das Kommentieren!
Deshalb meine Aufforderung an alle, Beschreibt das, was ihr da programmiert ausführlich! Es lohnt sich.

Ich möchte euch an einem Beispiel eines Deklarationskopfes zeigen wie so etwas aussehen kann.
Mit freundlicher Genehmigung von Herrn R. Tenhagen (im Automationssupport bei Moeller / EATON).

Code: [Auswählen]

(*
1 Funktionsbaustein : PT1

------------------------------------------------------------------------------
2 Name der Poe : FPPT1SA0
------------------------------------------------------------------------------
3 Programmierer : R. Tenhagen, Abteilung AA, Kloeckner-Moeller
------------------------------------------------------------------------------
4 Änderungsindex :
Version:0.1 Datum:18.2.97 Name:  Grund:

------------------------------------------------------------------------------
5 Ziel :
Der Eingangswert wird nach ein log. Kurve angepasst
Nach der Anstiegszeit ist ein Wert von ca 66% des Ausgangswertes
erreicht.
Der Wert könnte auch noch verstärkt werden
------------------------------------------------------------------------------
6 Beschreibung der Hardware : /
------------------------------------------------------------------------------
7 Besondere Variablen (für interne Übergabe)
 
------------------------------------------------------------------------------
8 Getestet :
------------------------------------------------------------------------------
*)
VAR_INPUT
Eingangswert_UINT : UINT ;
Anstiegszeit_s_UINT : UINT ;
Startwert_UINT : UINT ;
Verstaerkungsfaktor_UINT : UINT ;
END_VAR
VAR_OUTPUT
Ausgangswert_UINT : UINT ;
END_VAR
VAR
Zykluszeit : FPZYKZA0 ;
Startwert_gesetzt_BOOL : BOOL ;
Mittlere_Zykluszeit_mikro_s_UDINT : UDINT ;
Differenz_Aus_Ein_INT : INT ;
Eingangswert_INT : INT ;
Ausgangswert_INT : INT ;
Anstiegszeit_intern_s_UINT : UINT ;
Zykluszeit_aktuell_BOOL : BOOL ;
Divisionsrest_INT : INT ;
Divisor_INT : INT ;
Divisor_UDINT : UDINT ;
Zaehler_UINT : UINT ;
Verstaerkungsfaktor_intern_UINT : UINT ;
Verstaerkungsfaktor_intern_UDINT : UDINT ;
Ausgangswert_UDINT : UDINT ;
END_VAR
Ihr könnt auf den ersten Blick sehen, was der Baustein macht, ohne den Programmteil zu interpretieren.
Ich habe es nur um eine Versionsverwaltung unter Punkt 4 erweitert.
Die Variablen sind in Klartext mit Typangabe im Namen. Das macht auch das Programm leserlich.

Ich hoffe, ihr macht von dieser Vorlage reichlich Gebrauch!

Gruß Thomas