Programmablauf dokumentieren

  • VB.NET

Es gibt 17 Antworten in diesem Thema. Der letzte Beitrag () ist von cl10k.

    Programmablauf dokumentieren

    Hallo,

    ich muss mich leider mit der Dokumentation von Code beschäftigen. Ich habe mir bereits ein Buch über UML zugelegt und ein paar Videos angeschaut, werde aber noch nicht so richtig schlau daraus. Derzeit versuche ich (als Übung) den Ablauf eines (sehr einfachen) Programmteils darzustellen:

    Im Wesentlichen handelt es sich dabei um die Eingabe eines Users in ein UserControl, die anschließende Validarierung der Eingabe und ggf. Weiterleitung der Eingabe an eine Datenklasse.

    Vereinfacht habe ich den gesamten Vorgang bisher so dokumentiert:

    Quellcode

    1. Nutzereingabe
    2. TxBx_Input.TextChanged Event
    3. OnInput Methode
    4. HardValidation Methode
    5. fehlerhafte Eingabe:
    6. ErrorProvider aktivieren
    7. scls_ErrorManager.UpdateTabCorrectControlsCountOnHardValidation Methode
    8. korrekte Eingabe:
    9. scls_ErrorManager.UpdateTabCorrectControlsCountOnHardValidation Methode
    10. InputChanged Event (Weiterleitung der Eingabe an Datenklasse)


    Nun Frage ich mich wie ich das Ganze am Besten in ein Diagramm bringe und vor allem in welches. Ist ein Sequenzdiagramm die richtige Wahl? Ic habe den Eindruck, das Sequenzdiagramme eine höhere Abstraktionsebene darstellen und eher dafür geeignet sind, das Zusammenspiel von Klassen zu visualisieren. Aber was nimmt man dann für dieses Beispiel hier?

    Zusätzlich würde ich in diesem Diagramm gern kenntlich machen, welche Funktionalität durch Methoden, Funktionen, Events, etc bereitsgestellt wird. In den UML-Sequenzdiagrammen die ich bisher gesehen habe, kommunizieren allerdings nur generische Objekte miteinander - dort kann man nicht sehen, was sich tatsächlich hinter einem Objekt versteckt. Gibt es eine Möglichkeit das kenntlich zu machen?

    Ist UML überhaupt der richtige Weg? Bringt VS evtl sogar schon etwas Eigenes in der Richtung mit?


    EDIT: Ich bin jetzt einen Schritt weiter, ein Aktivitätsdiagramm scheint hier die bessere Wahl zu sein.

    Dieser Beitrag wurde bereits 3 mal editiert, zuletzt von „cl10k“ ()

    AFAIK gibts kaum ein System, um Programmabläufe zu dokumentieren. (Naja, mit EBC würds gehen, aber dassis speziell und unüblich)

    Schon ein normales Programm ist so komplex, dass du quadratmetergrosse Diagramme brauchen tätest. Die beste Doku eines Proggis ist sein Code. Dementsprechend stellt sich das Ding auch im ObjectBrowser dar (ggfs auch anhand der Doku-Tags im Code)

    Was meinst du mit "du musst dich damit beschäftigen"? Wer macht dich müssen?

    Hier - nimm einfach den PictureViewer.
    Dassisn total einfaches Program mit nichtmal einem OpenFolderDialog.
    Oder nimm halt PictureViewer mit LogIn - dasses sich wenigstens ein bischen lohnt.

    Probierma davon ein Diagramm zu machen.

    Dieser Beitrag wurde bereits 2 mal editiert, zuletzt von „ErfinderDesRades“ ()

    Hallo EDR,

    mein Chef macht mich müssen...

    Wir hatten einen ähnlichen Thread bereits an anderer Stelle, darum hier die Kurzfassung:

    Ich habe eine Software für eines unserer Institute geschrieben. Dort sitzen ausschließlich Physiker und Ingenieure - also größtenteils Programmieramateure (so wie ich). Meine Software soll von nachfolgenden Studenten weiter entwickelt und angepasst werden und darum muss (und will) ich eine Dokumentation schreiben die auch Laien ermöglicht, sich in ein verhältnismäßig komplexes Programm einzudenken und dieses dann zu verändern.

    Mir ist klar, dass es nicht sinnvoll ist zig tausend Zeilen Code in Diagrammform wiederzugeben - darum möchte ich in der Doku nur das grobe Konzept des Programmaufbaus und der Interaktion der Klassen wiedergeben, bei einigen wenigen Details dann auch zusätzlich Flowcharts.

    Ein detaillierter und umfassander Einblick in den Programmaufbau bietet dann der kommentierte Code selber.


    Ich merke es sogar selbst, wie schnell man den Überblick über sein eigenes Programm verliert: Ein paar Wochen nicht daran gearbeitet und schon vergisst man Details der Implementierung die in irgendwelchen Klassen gekapselt sind. Ich stelle es mir für einen Außenstehenden wirklich schwer vor sich da einzudenken. Da unsere Studenten vor allem im Rahmen von Bachelor- und Masterarbeiten daran arbeiten sollen, möchte ich es denen nicht noch schwerer machen als nötig.

    Dafür ist eigentlich UML vorgesehen. Muss aber dazu sagen, dass ich UML ab einem gewissen Zeitpunkt in Frage stelle. Und zwar genau ab dem wo ich anfange jede Methode usw. zu modellieren und ich mir teilweise stundenlang Diagramme anschaue um einen simplen Code zu verstehen. Aber wenn du das machen musst, dann wirds wohl auf Sequenzdiagramme, Aktivitätendiagramme etc. raus laufen.


    Opensource Audio-Bibliothek auf github: KLICK, im Showroom oder auf NuGet.

    cl10k schrieb:

    Mir ist klar, dass es nicht sinnvoll ist zig tausend Zeilen Code in Diagrammform wiederzugeben - darum möchte ich in der Doku nur das grobe Konzept des Programmaufbaus und der Interaktion der Klassen wiedergeben, bei einigen wenigen Details dann auch zusätzlich Flowcharts.
    Genau. Eine systematische Doku ist nicht möglich, allenfalls kann man einen groben Überblick verschaffen, und vlt. ein paar interessante Details.
    Wobei zusätzlich im Einzelfall noch zu gucken wäre, ob ein Diagramm (und welches) einen besseren Überblick verschafft als einfach ein paar Erläuterungen.

    Dass kommende Studenten dein Proggi fortentwickeln können halte ich für sehr fraglich. Falls es ühaupt gut gecodet war, werden sie es wohl in kürzester Zeit total verwüstet haben, die Noobs.

    ErfinderDesRades schrieb:


    Dass kommende Studenten dein Proggi fortentwickeln können halte ich für sehr fraglich. Falls es ühaupt gut gecodet war, werden sie es wohl in kürzester Zeit total verwüstet haben, die Noobs.


    Es ist nicht gut gecodet - aber es war ein lohnenswerter Lernprozess! Mein Programm modelliert ein umfangreiches technisches System, bestehend aus zahlreichen Untersystemen. Ich habe mich bemüht, strikt Infrastruktur/Verwaltung des Programms und die Modellierung der technischen Teilsysteme zu trennen. Wenn unserer Studenten etwas erweitern, dann diese technischen Teilsysteme - diese sind sauber in Klassen gekapselt und dort können sich die "Noobs" dann austoben - an die sonstigen Programmfunktionen müssen sie nicht ran.

    Was hältst du von einem Struktogramm ?

    EDIT: Sind zwar weder bunt noch unglaublich grafisch anspruchsvoll, aber ich finde die gut ^^
    »There's no need to "teach" atheism. It's the natural result of education without indoctrination.« — Ricky Gervais

    ThePlexian schrieb:


    EDIT: Sind zwar weder bunt noch unglaublich grafisch anspruchsvoll, aber ich finde die gut ^^


    *lach* :thumbsup:

    Ein Struktogramm ist mir zu detailliert. Wenn ich mich nicht täusche, sind Aktivitätsdiagramme die abstrakte Entsprechung der Struktogramme in UML. Ich möchte mich gern an einen Standard halten, der viele verschiedene Szenarien abdeckt. Ich benötige ja auch noch Klassendiagramme, etc. Da ist es vorteilhaft wenn es einheitlich ist.

    Ich habe mich eben mal schnell an Visio gesetzt (zum Glück gibt es MSDNAA) und einen ersten Versuch gestartet. Weiß noch nicht, ob ich mit der grundsätzlichen Richtung zufrieden bin...
    Bilder

    • ActivityDiagram_HardValidation.jpg

      41,1 kB, 749×947, 599 mal angesehen

    und was kann dieses Bildle nun einem Betrachter nützen?

    bist du dir ühaupt sicher, dasses korrekt ist?
    (Weil wenn bei mir eine harte Validierung fehlschlägt, dann gibts eher eine Exception, denn einen ErrorProvider.
    Schlimmer noch: ich code garkeine harte Validierung, sondern die ergibt sich ja grad daraus, dass eine Exception fliegt (etwa wenn eine Textbox an einen Zahlenwert gebunden ist, und jmd. gibt "hallo" ein)

    Dieser Beitrag wurde bereits 1 mal editiert, zuletzt von „ErfinderDesRades“ ()

    Fang an, das Programm selbst zu dokumentieren.
    Mach über jeder Prozedur, jeder Member-Variable, jedem Property, dedem Enum und jedem Wert im Enum usw. dies:

    VB.NET-Quellcode

    1. '''
    Dann generiert Dir die IDE einen Code, wo Du Deine Kommentare reinschreiben kannst:

    VB.NET-Quellcode

    1. ''' <summary>
    2. ''' Event-Handler von Button 1
    3. ''' </summary>
    4. ''' <param name="sender">Button, der das Event generiert hat</param>
    5. ''' <param name="e">Event-Parameter</param>
    6. ''' <remarks>Hier passiert dies und das</remarks>
    7. Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
    Wenn Du dann im Projekt -> Eigenschaften -> Kompilieren XML-Dokumentationsdatei generieren

    einen Haken setzt, wird neben der Exe eine XML-Datei erzeugt, in der all diese Kommentare drin stehen:
    XML-Kommentar-Datei

    XML-Quellcode

    1. <?xml version="1.0"?>
    2. <doc>
    3. <assembly>
    4. <name>
    5. Test Timer
    6. </name>
    7. </assembly>
    8. <members>
    9. <member name="P:Test_Timer.My.Resources.Resources.ResourceManager">
    10. <summary>
    11. Gibt die zwischengespeicherte ResourceManager-Instanz zurück, die von dieser Klasse verwendet wird.
    12. </summary>
    13. </member><member name="P:Test_Timer.My.Resources.Resources.Culture">
    14. <summary>
    15. Überschreibt die CurrentUICulture-Eigenschaft des aktuellen Threads für alle
    16. Ressourcenzuordnungen, die diese stark typisierte Ressourcenklasse verwenden.
    17. </summary>
    18. </member><member name="T:Test_Timer.My.Resources.Resources">
    19. <summary>
    20. Eine stark typisierte Ressourcenklasse zum Suchen von lokalisierten Zeichenfolgen usw.
    21. </summary>
    22. </member><member name="M:Test_Timer.Form1.Button1_Click(System.Object,System.EventArgs)">
    23. <summary>
    24. Event-Handler von Button 1
    25. </summary>
    26. <param name="sender">Button, der das Event generiert hat</param>
    27. <param name="e">Event-Parameter</param>
    28. <remarks>Hier passiert dies und das</remarks>
    29. </member>
    30. </members>
    31. </doc>
    Falls Du diesen Code kopierst, achte auf die C&P-Bremse.
    Jede einzelne Zeile Deines Programms, die Du nicht explizit getestet hast, ist falsch :!:
    Ein guter .NET-Snippetkonverter (der ist verfügbar).
    Programmierfragen über PN / Konversation werden ignoriert!

    Hallo Rod,

    diesen Tipp hattest du mir bereits vor einiger Zeit gegeben. Die Idee einer automatisch generierten XML Datei ist fantastisch. Derzeit nutze ich es nur im "Klassenkopf" um grob einen Überblick zu geben, was in der Klasse passiert. Der Rest des Codes ist mit normalen einzeiligen Kommentaren versehen.

    Mir war bisher nicht klar, bis zu welchem Exzess man diese XML Doku treiben kann (sollte?). Ich werde mich heute Abend mal daran setzen, eine Klasse komplett durchzuarbeiten und mal schauen wie das Ergebnis aussieht und ob es eine besseres Verständnis ermöglicht.


    Hallo EDR,

    Das Bild selber war nur eine Fingerübung um in Visio ein solches Diagramm zu basteln.

    Zum Konzept das dargestellt ist:

    Hier hängt ein UserControl (im Grunde eine Textbox mit schnickschnack) per DataBinding (OnPropertyChange) an einer Datenklasse. Die Textbox kennt den Datentyp der angebundenen Datenklassenproperty. Gibt der User nun ein falsches Format ein (Buchstaben statt Zahlen, Single statt Integer, etc.) wird durch die HardValidation das Event unterdrückt, welches das Binding "aktualisiert" und statt dessen der ErrorProvider angeworfen. Ich möchte sicherstellen, dass kein Müll bis auf die Ebene der Datenklassen kommt.

    Welchen Vorteil bringt es eine Fehleingabe mit einer Exception zu quittieren? Welches Feedback ergibt sich daraus für den Nutzer?

    Zielt deine Frage darauf ab, die normalen (bereits vorhandenen) Validierungsroutinen zu benutzen? Diesen Ansatz habe ich nach ausführlichem Test vor langer Zeit verworfen. Ich benötige zwingend ein Binding mit OnPropertyChange-Funktionalität.

    meine Frage zielt genau auf die Frage: Was nützt es jmd, der dein Proggi weiterentwickeln will, wenner dies bildle angugge tut.
    ich tippe auf: annähernd garnix.
    Mach lieber ein paar Sätze, wie du hier jetzt auch gemacht hast, dasses ein ucl ist, mit Validierung und Databinding.

    Und zu so Xml-Doku-Exzessen habich voll die Rod-konträre Meinung: guter Code dokumentiert sich selbst, also wäre Button1 nur vernünftig zu benennen, und weitere Erklärungen erübrigen sich oft (angenommen, der Button heißt "btCancel", dann ist da kaum noch was zu erklären. Vor allem darf da nicht "erklärt" werden, dass dort gecancelt wird, weil dassis tautologische Leser-Verarsche)
    Doku-Kommentare

    Erstmal Danke für deine Anmerkung! Ich bin froh über jeden Denkanstoß der mich zwingt festgefahrene Wege zu überdenken. Da du auf die Validierungsgeschichte nicht mehr eingegangen bist, gehe ich davon aus , dass das Konzept i.O. ist...

    Ich habe nicht vor, die gesamte Doku aus Diagrammen zu machen. Ich befürchte nur, dass bei komplexeren Abläufen, reiner Text schwer nachvollziehbar ist. Meine Idee ist bisher, sowohl Text als auch Diagramme zusammen einzusetzen. So hat man eine ausführliche Erklärung und ein Bildchen um den Vorgang zu visualisieren. Aber ich stehe mit meiner Doku noch ganz am Anfang. Mal schauen was sich als praktikabel herausstellt.


    Dein Kommentar zu Rods XML:

    Wir hatten eine ähnliche Diskussion bereits. Für einen geübten Programmierer ist es nicht schwer einen sauberen Code zu begreifen. Eine korrekte Benennung ist dabei noch der einfachste Teil (und sollte selbstverständlich sein).

    Aber was mache ich mit einem Anfänger der noch nie von DataBinding gehört hat, der nichts davon weiß das Eingaben validiert werden müssen und der keine Ahnung hat, wie die Eingabe in eine Textbox über eine Kette von Events und Methoden schließlich zu einer Änderung einer Datenklassenproperty führt?

    Je besser (nicht zwangsläufig umfangreicher) ich dokumentiere, desto schneller kann sich derjenige auf seine eigentliche Aufgabe konzentrieren. Vergiss bitte nicht, dass meine "Zielgruppe" Ingenieure mit nur rudimentären Programmierkenntnissen sind...

    Eine Programm-Doku sollte imo nicht versuchen, dem Leser Programmier-Grundkenntnisse beizubringen. Guter Code erklärt sich selbst, und wers nicht versteht, sollte eh nicht drin rumpfuschen.

    ich glaub auch nicht, dass einem Anfänger geholfen ist, wenn eine Sub New kommentiert wird mit "hier wird ein neues Dingsbums-Typ-Objekt erstellt".

    Besser wäre: "Konstruktor. Wer nicht weiß, was ein Konstruktor ist: dieses Buch lesen (hingegen das Galileio-Openbook ist Mist)"

    Aber ich denk eh, du wirst eine ganz spezielle Doku erstellen. Mit vlt. einem Überblick über die allgemeine Funktionsweise, und dann detaillierter darauf eingehen, wo du Erweiterbarkeit vorhersiehst.
    Und an Medien musste halt gucken, was der Kundschaft am verständlichsten sein mag - vlt. drehste auch ein Tutorial-Video.

    Hallo Rod und alle Anderen,

    du scheinst mit den XML-Kommentaren ja bereits Erfahrung zu haben. Ich habe bisher vergeblich nach einer Übersicht gesucht, in der Details zur Formatierung dieser Kommentare aufgelistet sind. Auf den Nägeln brennt mir vor allem ein einfacher Zeilenumbruch und die Möglichkeit auf andere Methoden mit einer Art Hyperlink zu verweisen. Hast du dazu irgend etwas schlaues in deiner Trickkiste?

    lg

    cl10k schrieb:

    Hyperlink
    Probier mal dies:

    VB.NET-Quellcode

    1. ''' <summary>
    2. ''' xxx yyy <see cref="Form1"/>
    3. ''' </summary>
    4. ''' <param name="index">Der Index halt</param>
    5. ''' <remarks>ein Test</remarks>
    6. Private Sub Test(ByVal index As Integer)
    8. End Sub
    In ''' xxx yyy <see cref="Form1"/> muss eine existierende Klasse stehen (hier: Form1).
    Falls Du diesen Code kopierst, achte auf die C&P-Bremse.
    Jede einzelne Zeile Deines Programms, die Du nicht explizit getestet hast, ist falsch :!:
    Ein guter .NET-Snippetkonverter (der ist verfügbar).
    Programmierfragen über PN / Konversation werden ignoriert!

    Hallo EDR,

    ich kannte das Video bereits.

    Ich nutze den Objektbrowser schon eine Weile, allerdings ist es ein schrittweiser Prozess bis einem mal klar wird, wie konsistent und weitreichend der Objektbrowser in das System integriert ist. Ich wäre nie auf die Idee gekommen mir ne Hilfe zu summary aufzurufen... Mittlerweile habe ich dann auch bemerkt das Intellisense sogar Vorschläge macht, sobald man die eckige Klammer schreibt. (Hätte man auch eher drauf kommen können...)

    Hallo Rod,

    dank deines Tipps habe ich die richtigen Beispiele im Netz gefunden, aber ich stehe immer noch auf dem Schlauch. Ich habe einfach mal das Standardbeispiel von hier in eine Klasse eingefügt:

    VB.NET-Quellcode

    1. ''' <param name="id">The ID of the record to update.</param>
    2. ''' <remarks>Updates the record <paramref name="id"/>.
    3. ''' <para>Use <see cref="DoesRecordExist"/> to verify that
    4. ''' the record exists before calling this method.</para>
    5. ''' </remarks>
    6. Public Sub UpdateRecord(ByVal id As Integer)
    7. ' Code goes here.
    8. End Sub
    10. ''' <param name="id">The ID of the record to check.</param>
    11. ''' <returns><c>True</c> if <paramref name="id"/> exists,
    12. ''' <c>False</c> otherwise.</returns>
    13. ''' <remarks><seealso cref="UpdateRecord"/></remarks>
    14. Public Function DoesRecordExist(ByVal id As Integer) As Boolean
    15. ' Code goes here.
    16. End Function


    Erwarten würde ich unters Remarks einen "Link" für DoesRecordExist. Aber nada?! (siehe Bild)
    Bilder

    • Unbenannt.PNG

      93,59 kB, 1.214×748, 401 mal angesehen

Facebook
Telefonspende