Moin moin miteinander,
ich bin gerade im Abschluss meiner Technikerarbeit, jetzt stellt sich
die Frage, wie ich meine Software (Relativ kleines vb.net Programm am PC
zu Verwaltung) und ca 2200 Programmzeilen Code im Controller.
Wie stellt man sowas nun schön dar?
Eine PAP oder Struktogramm bis ins letzte Detail wäre ja ein absolut
unüberschaubares Werk, und man würde viel schneller durch den gut
kommentierten code steigen.
Wie macht man sowas üblicherweise?
Ein PAP, bei dem lediglich klartextbeschreibungen und als Pseudocode die
Funktionsaufrufe stehen?
Würd mich über ein paar Anregungen freuen!
Liebe Grüße
Jens
Funktionsbeschreibung vielleicht was die Software macht und kann?
Kommt immer auch drauf an wer es liest. Da sollte man die oder den
mal fragen, ansonsten gibts da zich Möglichkeiten. Jede tiefere
Dokumentation dient eher dem Programmierer, wenn man etwas verbessern
oder ändern will, insbesondere wenn es jemand anders ist.
Ansonsten hat man ja die Kommentierung im Listing die man ja
je nach Wunsch ausführlich machen kann.
Jens Plappert schrieb:> Wie stellt man sowas nun schön dar?
Am liebsten garnicht.
Sinnvoll ist die Dokumentation von Schnittstellen, etwa APIs. Da hat
sich bei C-ähnlichen Sprachen Doxygen/qtdoc/javadoc etabliert, für Basic
hat sich Microsoft sicherlich auch etwas völlig Unleserliches und
Sperriges mit viel XML ausgedacht :-}
Im Quelltext selbst dann genau dort Kommentare, wo sie angebracht sind.
Plattheiten ('bla setzen', 'Funktion aufrufen') solltest du vermeiden,
du hast ja den Quelltext schon formuliert. Also brauchst du in der Regel
nicht dasselbe nochmal auf Hochdeutsch drüber zu kommentieren.
Kommentare sollen nämlich entgegen der Meinung vieler Manager nicht den
Quelltext nachplappern, sondern ergänzende Informationen zum Verständnis
liefern.
Von UML/PAP/Struktogrammen lasse ich schon lange die Finger. UML hält
fast immer nur unnötig auf, ohne einen sinnvollen Beitrag zum
Projektfortschritt zu leisten. PAP und Struktogramme sind bei
ereignisorientierter Programmierung (GUI) meistens kaum zu handhaben.
Für komplexe Algorithmen geht ein PAP aber nach wie vor voll in Ordnung,
ohne Frage.
Problematisch wird es später, wenn Programm und PAP auseinandergehen.
Etwa, weil nachträglich Änderungen ins Programm geflossen sind und
niemand den PAP aktualisiert hat. Als Entwickler hält man sich dann
sinnvollerweise an den Quelltext, denn der läuft ja (hoffentlich).
Das sollte natürlich nicht passieren. Tut es aber leider, insofern spar
ich mir die Mühe mittlerweile und halte dafür lieber den Quelltext
sauber.
Sven P. schrieb:> Problematisch wird es später, wenn Programm und PAP auseinandergehen.
Der Fall dürfte bei einer Technikerarbeit eher die Ausnahme sein.
> und halte dafür lieber den Quelltext sauber.
Ja, das ist sehr wichtig - nur ist Basic dabei eher hinderlich.
Ich halte es so, daß im Funktionskopf kurz der verwendete Algorithmus in
Schritten sizziert wird und die einzelnen Schritte dann im Code markiert
sind. So kann man auch nach längerer Zeit noch nachvollziehen, was man
sich mal gedacht hat, als man das Ding entwarf.
Der ganze Formalkram, der als extra-Dokument zum Quelltext gepflegt
werden muß, ist unbrauchbar, weil er im "richtigen Leben" schneller
veraltet, als aktualisiert ist.
Genau so meinte ich das.
Separate Dokumentation kann man anlegen für wichtige Algorithmen. Die
beschränkt sich dann aber sinnvollerweise darauf, den Algorithmus selbst
und nicht seine Umsetzung in irgendeiner Programmiersprache zu
beschreiben.
Vielen Dank für die ausführlichen Antworten.
Ich setz mich auf jeden Fall nochmal mit dme Betreuer zusammen, um zu
erfahren ob und wie genau ein PAP oder ähnliches erstellt werden muss.
Ich selbst halte da für einfach Sachen ja auch nicht besonders viel von.
Ich habe im Quelltext z.B. 3 oder 4 Zeilen kurz im Kommentar erklärt wie
sich bei mir die Menunavigation mit einem Array und den Breaks aufbaut
und danach die einzelnen (selbsterklärend betitelten) Punkte
"abprogrammiert". Meiner Meinung nach reicht sowas. Mal sehen, was der
Cheffe dazu meint ;-)
Code im Quelltext sauber dokumentieren ist schon die halbe Miete. Das
geht z.B. mit Doxygen. Das Zusammenspiel des grossen Ganzen, die
Architektur, beschreibt man separat, am besten auch etwas grafisch. Wo
man eben sieht, welche Module miteinander wie verknüpft sind. Besonders
komplizierte Algorithmen ebenfalls separat beschreiben, wenn
gewissermassen als Forschungsergebnis deiner Arbeit dastehen. Da musst
du wiederum entscheiden, wie du das am besten darstellst - kommt sehr
auf den konkreten Fall an.
PAP und Struktogramm sind zur Dokumentation Humbug, ausser eben
allenfalls für die Detailbeschreibung eines wichtigen, komplizierten
Algorithmus.
P. M. schrieb:> Code im Quelltext sauber dokumentieren ist schon die halbe Miete. Das> geht z.B. mit Doxygen.
Wobei man Doxygen nur benötigt, wenn die Doku separat rausgezogen
werden soll. Bei einer Technikerarbeit halte ich das für nicht so
wahrscheinlich. Sinnvolle Kommentare kann man auch ganz ohne
Doxygen schreiben. ;-)
Bei BASIC muss man dann sehen, wie man das brauchbar strukturieren
kann, damit man die einzelnen Bestandteile auch optisch erkennt.
Wenn auf beiden Seiten (PC und MCU) Statemachines implementiert sind,
d.h. die Programme reagieren auf Events, dann sind Zustandsgraphen
(graphviz) und Message Sequence Charts (mscgen) das Mittel der Wahl.
Man kann solche Bilder natuerlich auch haendisch z.B. mit
LibreOffice Draw oder Visio zeichnen.
Auch wenn Basic von Doxygen nicht direkt unterstuetzt wird, kann man
sich mit einem Filter helfen:
http://www.sevo.org/2010/06/doxygen-und-visual-basic-net/
Axel Wachtler schrieb:> dann sind Zustandsgraphen> (graphviz) und Message Sequence Charts (mscgen) das Mittel der Wahl.
Hoffentlich ist die state machine nicht so groß, sonst muss man der
Arbeit ein A0-Blatt beilegen. :-)) (SCNR)
:-P Das wärs noch.
Aber das stimmt, gerade die zwei Gegenüberstehenden Statemachines wären
vielleicht wirklich ganz Interessant,vielleicht auch noch die des
MIDI-Empfanges.
Der Hauptbatzen ist ja die Firmware, die ist zwar in Basic, aber eben
eins ehr Hadrwarenahes Basic, da sehe ich in der Strukturierbarkeit
ehrlich gesagt keinen Unterschied zu C.
