# Softwaredokumentation



## MariusW (11 Februar 2010)

Hallo,

das alte leidige Thema der Softwaredokumentation. Mich würde einmal interessieren wie Ihr im S7 Variablen, Netzwerke, Header, FB's; und FC's kommentiert. 


Gruß Marius


----------



## janusz (11 Februar 2010)

Hallo Marius, 
als bei mir ist JEDER der nicht kommentiert ein persönlicher Feid - zum Abschuss freigegeben. Ich hasse es, wenn ich immer wieder vor Problem : "was wollte der Künstler uns damit sagen ?"  stehe. Also wenn um mich geht wird im Prinzip ALLES kommentiert, daß heist:
1. Jedes Netzwerk als Überschrifft - Funktion: was wird dort gemacht und manchmal: wozu
2. Im AWL : jede Programmzeile
3. Im jedem FC/FB genaue Beschreibung von : Zweck, Ersteller, Version-Nr., was macht der Baustein und auf welche weise.
Und so weiter, u.s.w...
Ich muß dir sagen, ich liebe es wenn Kunden genaue vorgaben hier machen und danach KONTROLLIEREN !! Ein Kollege von mir hatte ganze 4 Wochen in China auf eigene Kosten gesessen und sein Programm kommentiert, weil der Endkunde es abgelehnt hatte, die Abnahme zu unterschreiben.
Mir ist schon passiert, daß ich dem Kunden das ganze (oder Teile vom) Programm neu geschrieben habe, weil das Alte nicht zu gebrauchen war, da keine Kommentare.
Janusz


----------



## Kieler (11 Februar 2010)

Also tendenziell sehe ich es genau wie janusz. Ich bin jetzt jetzt fast 20 Jahre dabei. Ich kann mich nicht erinnern, ein so gut dokumentiertes Programm gesehen zu haben, wie es janusz beschreibt. Aber ich habe schon ganz viele Programme gesehen, in denen nichts kommentiert war. Letztes Jahr hatte ich ein recht großes Programm in FUP mit sehr vielen Merkern (warum auch immer). Keiner hatte ein Symbol oder Kommentar. Es gab zwar NW-Überschriften, aber der Sinn blieb trotzdem dunkel.

- erstmal muss ein Programm vernünftig strukturiert sein
   mit Antriebsbausteinen
   mit Funktionsgruppen usw
- der Symbolische Name sollte kopierfreundlich sein
   alle Symbole von Pumpe 1 und Pumpe 2 sind identisch und unterscheiden 
   sich  nur in PU1xxxx und PU2xxxxx
   Das Gleiche gilt für Maschine A und B mit jeweils 20 Pumpen
Jedes Netzwerk erhält eine Überschrift und häufig machen auch ein paar Zeilen Kommentar Sinn.

Wenn man selbst Pflichtenheft/Funktionsbeschreibung etc. macht, macht es auch Sinn die Beschreibung analog zu den Bausteinen aufzubauen.


----------



## uncle_tom (11 Februar 2010)

Servus,

also ich kommentiere ja auch fleissig und reichlich. Ich hasse es auch, wenn ich vor einem fremden Programm sitze, indem keine Kommentare ja geschweige denn Symbolnamen vergeben sind :twisted:

aber wie von janusz beschrieben



janusz schrieb:


> 2. Im AWL : jede Programmzeile



jede Programmzeile zu dokumentieren, das finde ich etwas übertrieben.

Bsp.: Addition von 5 REAL-Werten


```
//Berechnung von BlaBlaBa

L #Wert1
L #Wert2
+R
L #Wert3
+R
L #Wert4
+R
L #Wert5
+R
T #Ergebniss

//Naechster Block
...
```
hier sollte es ja ausreichen, wenn der Sinn der Addition kommentiert ist.

Mfg
uncle_tom


----------



## janusz (11 Februar 2010)

Hallo ihr beiden 
selbstverständlich habt ihr beide Recht .-) soooo fleissig bin ich auch nicht. Einfache Operationen die sogar für "dummies" sofort erkennbar sind, werden nicht (oder selten) von mir kommentiert. Grundsätzlich gehe ich aber von der Annahme aus, daß ich nicht beweisen muß was ich für ein toller Programmierer bin und am Ende nur ein Betriebselektriker (oft im Ausland auch ohne besondere Ausbildung) sich ev. damit beschätigen wird. 
Nichtdestoweniger betrachte ich ein Programm ohne Kommentare als Schrott und ein Zeichen von Faulheit und Arroganz des Programmierers.
Grüße
Janusz


----------



## MariusW (12 Februar 2010)

Guten Morgen,

erstmal danke für eure Meinungen. Hoffe das da noch ein paar mehr kommen. Bekommt man das mit dem Kommentieren nicht auch schon in der Ausbildung beigebracht?

@ janusz

"Einfache Operationen die sogar für "dummies" sofort erkennbar sind.......", auch diese Funktionen sollten zumindest mit einer "Überschrift" beschrieben werden. Damit auch die Jungs aus der Doku damit zurecht kommen.


----------



## janusz (12 Februar 2010)

@MariusW

ist doch Klar, mein Post war bezogen auf die Antwort von Uncle - in so einem Fall wie seins mache ich keine Zeilenkommentare - das war damit gemeint. Sonst gibt es eine Regel: kein Netzwerk ohne Kommentar - im schlimmsten Fall "copy&paste"
Und mit den "dummies" war nicht abwertend gemeint  (diesen Begriff sollte mein mit "Beginners" assozieren), ich weiss sehr gut, daß kein Meister vom Himmel gefallen ist und jeder auch irgendwann lernen Muß.
Ob man das in der Ausbildung mitbekommt? Keine Ahnung, manchmal habe ich meine zweifel. Ich habe das sozusagen im Blut da ich als älterer semester vom Assembler programmierung komme - dort kriegt man das Kommentieren mit Schweiss und Tränen eingebrannt 
Grüße
Janusz


----------



## MariusW (12 Februar 2010)

@janusz
das war mir schon bewust! ;-)


----------



## pvbrowser (12 Februar 2010)

Ich finde, diese Diskussion zeigt mal wieder, dass es besser wäre SPS'en in einer Hochsprache zu programmieren.

Das hier erinnert mich mehr oder weniger an die Art und Weise, wie man Assembler programmiert.
In einer Hochsprache kann man Variablen und Funktionen sinnvolle Namen geben und man kann objektorientiert programmieren.

Kommentare haben den Nachteil, dass sie von Compiler ignoriert werden.
In schlimmsten Falls können Kommentare irrelevant oder gar falsch sein.

Wenn ich jetzt in einer Hochsprache wie C/C++ programmieren
kann, habe ich eine Vielzahl ausgereifter Werkzeuge zur Verfügung.
Z.B. kann man mit
http://www.stack.nl/~dimitri/doxygen/
Programmcode hervorragend gut dokumentieren.
Die "Prosa" wird dabei in speziell formatierten Kommentaren im Quelltext selbst untergebracht.

Diese Vorgehensweise verwende ich jedenfalls, wenn ein PC (auch embedded) + Remote I/O eingesetzt wird.

Wenn sich nun ein Anbieter (China|Korea ???) finden würde,
der eine SPS auf den Markt bringt, die mit C/C++ programmiert werden kann, bin ich sofort dabei.

Eine SPS ist ja nix weiter als ein kleiner Computer + I/O in einem industrietauglichen Gehäuse für den Schaltschrank.


----------



## marlob (12 Februar 2010)

pvbrowser schrieb:


> ...
> Das hier erinnert mich mehr oder weniger an die Art und Weise, wie man Assembler programmiert.
> In einer Hochsprache kann man Variablen und Funktionen sinnvolle Namen geben und man kann objektorientiert programmieren.
> ...


Also kann ich in TwinCAT oder RSLogix oder so den Variablen und Funktionen keine sinnvollen Namen geben?
TwinCAT hat jetzt auch objektorientierte Erweiterungen



pvbrowser schrieb:


> ...
> Kommentare haben den Nachteil, dass sie von Compiler ignoriert werden.
> In schlimmsten Falls können Kommentare irrelevant oder gar falsch sein.
> ...


Hatte ich vergessen. In einer Hochsprache können Kommentare nicht 
"irrelevant oder gar falsch sein."



pvbrowser schrieb:


> ...
> Wenn ich jetzt in einer Hochsprache wie C/C++ programmieren
> kann, habe ich eine Vielzahl ausgereifter Werkzeuge zur Verfügung.
> Z.B. kann man mit
> ...


Es steht jedem frei, doxygen so zu erweitern um auch den Programmcode
von SPS-Programmen zu dokumentieren



pvbrowser schrieb:


> ...
> Wenn sich nun ein Anbieter (China|Korea ???) finden würde,
> der eine SPS auf den Markt bringt, die mit C/C++ programmiert werden kann, bin ich sofort dabei.
> ...


TwinCAT kannst du in einer Hochsprache programmieren. Die kommen nur
leider nicht aus "China|Korea"


----------



## MariusW (12 Februar 2010)

Soll die neue 1000er von Siemens nicht in hochsprache programmierbar sein?


----------



## Blockmove (12 Februar 2010)

pvbrowser schrieb:


> Ich finde, diese Diskussion zeigt mal wieder, dass es besser wäre SPS'en in einer Hochsprache zu programmieren.


 
Sorry, aber hier widerspreche ich jetzt mal ganz erheblich!
Die Programmiersprache hat wenig mit der Kommentierung zu tun.
Ich habe selbst in der vergleichsweise konservativen S7 die Möglichkeit Strukturen und UDT zu nutzen und somit quasi "selbstkommentierende" Programme zu schreiben.
Nur nutzen und können muß man es halt. Und das ist bei C oder C++ nicht anders.

Gruß
Dieter


----------



## Guts2 (12 Februar 2010)

Huhu,

Ich bin Programmiere und kann sowohl Hochsprache, als auch Assembler uns die üblichen SPS Sprachen.

Obwohl ich noch Anfänger bin versuche ich das beste aus allen 3 Welten mit einander zu kombinieren.

Das heist das ich viele kommentare setzte und versuche Objektorientiert meine Programme in viele kleine Teillösungen runter zu brechen.

-> Gleiche Motoren bekommen eigenen Baustein.

-> Alle Motoren kommen in einen Motoren Programmbaustein.

-> Die Motoren werden von einer Schrittkette angesteuert. 

-> Variabel für z.B. Motoren werden in Motor Datenbausteine gesammelt.

So bekomme ich eine Übersicht in meine Programme und kann auch alles schön kommentieren.

Sollte es dann doch mal zu problemen kommen, dann kann ich einfach rückwärts gehen und weiß dann wo alles steht und komme schnell zu meinem Ziel 

Aber wie gesagt, das ist die Ansicht eines Anfängers. Die alten Hasen haben sicher bessere Lösungen


----------

