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)
>Hoffentlich ist die state machine nicht so groß, sonst muss man der >Arbeit ein A0-Blatt beilegen. :-)) (SCNR) Obwohl so ein Stueck Techniker-Origamie nach DIN824 die Arbeit sicher aufwertet ;-) http://web.archive.org/web/20080621005033/www.mb.fh-stralsund.de/cad/websites/Normen/DIN824.html
:-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.
Thread beobachten
Seitenaufteilung abschaltenBitte melde dich an um einen Beitrag zu schreiben. Anmeldung ist kostenlos und dauert nur eine Minute.
Bestehender Account
Schon ein Account bei Google/GoogleMail? Keine Anmeldung erforderlich!
Mit Google-Account einloggen
Mit Google-Account einloggen
Noch kein Account? Hier anmelden.