VBA Projektdokumentation

[Case]

Wenn es schon nicht dazu dient dass es wirklich jemand versteht sollte es zumindest einen professionellen Eindruck machen / visuell professionell aussehen.

Dann nimm die MZ-Tools. Nicht kostenfrei, aber auch bei zukünftigen Projekten sehr hilfreich. Da kannst du unter Anderem eine XML-, oder HTML-Dokumentation erstellen lassen.

[Zwenn]

Hallo StrammerMax,

wenn ich mir Deine Postings so durchlese, lokalisiere ich zwei Probleme:
1. Ein fremd verschuldetes: Du sollst das Projekt so Reporten, dass ein Laie es warten kann.
2. Ein selbst verschuldetes: Mangelnde Kommentierung/ Protokollierung

zu 1.
Wer solche Forderungen stellt, weiß nicht wovon er redet. Es ist schlicht und ergreifend nicht möglich einem Laien das Programmieren/ Entwickeln von Software im Rahmen einer Projektdokumentation beizubringen. Mach das Deinem Chef oder wer auch immer diese Schnappsidee hatte klar. Wenn er es nicht begreift, besorge ein paar Bücher, nur zu den Grundlagen und lege sie ihm auf den Tisch. Dazu kannst Du anmerken, dass selbst das Lesen dieser Bücher nicht zum Ziel führt. Entwickeln funktioniert nicht nach Schema F. Um das zu lernen muss man entsprechende Denkstrukturen ausbilden. Das ist wörtlich zu nehmen. Man muss sein Gehirn darauf schulen. Wenn Dein Auftraggeber das nicht begreift, lass ihn Rekursion erklären. Das ist der Klassiker, an dem jeder erstmal zu knabbern hat, weil das paralleles bzw. mehrschichtiges Denken erfordert. Das kann kein Mensch von Haus aus, weil es für uns kein natürlicher Prozess ist. Das kann man auch sehr gut daran sehen, dass Rekursion in der freien Wildbahn eher selten verwendet wird.

zu 2.
Je nachdem, wie kompliziert ein zu kommentierendes Code-Fragment ist, würde ich es immer granularer kommentieren, bis hin zu zeilenweise. Oft reicht aber auch z.B. über einer Schleife zu erklären, was sie macht. Am Anfang einer Funktion sollte man eigentlich immer erstmal einen kurzen Text schreiben, was die Funktion macht, was ihre Eingangsparameter sind und was sie ausgeben soll. Außerdem sollte da drin stehen, wann die Funktion erstellt wurde und wann was an ihr geändert wurde. Ich schreibe soll man machen, weil ich dazu ehrlich gesagt meistens selbst zu faul bin. Dafür kommentiere ich aber sehr viel im Quelltext. Wie schon im oben von Elex verlinkten Thread von Dir erwähnt, ist nur zu hoffen, dass Du sprechende Namen für die Variablen und Konstanten gewählt hast. Allein das bringt schon sehr viel für das Verständnis von Quellcode.

Allgemein
10.000 Zeilen sind natürlich schon mal rein von der Menge her ein Brett. Du könntest auf Papier aufmalen, was die einzelnen Prozeduren machen und wie sie miteinander interagieren. Dabei wird Dir selbst nochmal viel klar werden. Aber redundanten Code wirst Du vermutlich nicht mehr vor dem Abgabetermin eindampfen. Das kannst Du auch anschließend machen und dann "in Ruhe" dafür sorgen, dass die Funktion des Ganzen auch weiterhin gegeben ist. Vorher würde ich die Gelegenheit dann aber nutzen und abwarten, welche Wünsche oder Anmerkungen zu Macken an Deinem Projekt aus Anwendersicht kommen. Je nachdem wie groß der Anwenderkreis ist, sei Dir sicher, bei einem so umfangreichen Projekt kommt mit Sicherheit entsprechendes Feedback.

StrammerMax
...
Zudem haben Änderungen im Code teilweise gravierende Auswirkungen. Da ich von Anfang an alles ohne Namen, mit festen Zuweisungen von Zeilen implementiert habe würde es alles zerschießen, wenn jemand auch nur eine Zeile löscht oder hinzufügt.
...

Das ist ein ziemlicher SuperGAU. Statt das nachträglich zu flicken, dürfte der Vorschlag von Sulprobil zielführender sein, das Projekt neu aufzusetzen. Dann aber vorher mal ein paar Notizen machen, was passieren soll und wie Du es umsetzen willst. Eine Art Blaupause hast Du Dir ja schon auf etwas chaotische Weise geschaffen. Führe Dir an dieser Stelle vor Augen, bevor man umfangreichere Dinge angeht, muss man sie planen. Das ist ein iterativer Prozess. Man kann bei größeren Projekten nicht einfach drauf los programmieren. Das kann nur nach hinten losgehen. Analog dazu kannst Du den Bau eines Hauses betrachten. Niemand würde auf die Idee kommen einfach ein paar Säcke Zement und einen Haufen Ziegelsteine zu bestellen und loszumauern, wie es einem grade einfällt. Nein, zuerst plant ein Architekt so ein Haus. Man spricht nicht umsonst vom Software-Architekten (wenn auch nicht offiziell, da Architekt eine geschütze Berufsbezeichnung ist.)

Du wirst wohl jetzt erstmal in den sauren Apfel beißen müssen und die Dokumentation nachträglich erarbeiten müssen. Es ist zwar kein Trost, aber ich nehme mal an, da mussten wir alle irgendwann mal durch, weil am Anfang von jedem (den ich kenne jedenfalls) Kommentierung als völlig überflüssig angesehen wird. Nach einer solchen Erfahrung, wie Du sie grade auch noch in einem umfangreicheren Projekt  machst, ist man von dieser Ansicht geheilt :99:

Viele Grüße,

Zwenn

[Sulprobil]

Ein Lessons learned Kapitel ist auch sinnvoll:
Welche Fehler man hatte, wie sie gelöst wurden, und wie man sie verhindert.
Welche jüngste größere Änderung durchgeführt wurde und was dabei wichtig war.

Dann hast schon viel abgedeckt.

Viele Grüße,
Bernd P

[Käpt'n Blaubär]

Hallo,

Wenn der Chef aber nach einer Dokumentation verlangt muss ich ihm auch eine liefern
- unabhängig davon, wie sinnvoll das ist.

tja, so isses eben. Der Chef hat nicht nur recht, sondern der hat auch Recht. Er muß sich um die
Zukunft kümmern und  dafür sorgen, daß der Laden unter allen Umständen ruckelfrei läuft.

Ich würde die Gelegenheit nutzen, aus dem unübersichtlichen Codehaufen modulare Teilstücke
zu basteln und diese vernünftig zu dokumentieren. Ein modularer Aufbau macht den ganzen
Kram übersichtlicher und sehr viel pflegeleichter.
Ich weiß auch, von welchem Aufwand ich spreche. Ich habe vor Jahren meinen Datenbestand
von Multiplan nach Excel konvertiert und da VBA damals noch deutsch sprach, dann später noch
einmal in das englische VBA. Das war ganz schön schweißtreibend.

[StrammerMax]

- die Bezeichnungen sind (natürlich) nicht sprechend gewählt :19:  Daher fällt es selbst mir schwer nachzuvollziehen was ich da gemacht habe.  Ihr kennt das sicher... wenn man mal im "Tunnel" ist und Probleme hat bastelt man so lange, bis es irgendwie funktioniert.
Wenn man sich das 3 Wochen später anschaut versteht man die Hälfte selbst nicht mehr. Natürlich hätte man es am besten gleich im Code kommentiert - aber das lässt sich im Nachgang immer leicht sagen.

Neu bauen (lassen) wäre mit Sicherheit die einfachste Möglichkeit - allerdings fehlt mir 1. die Zeit dazu und 2. die Kompetenz.
Mir ist jetzt natürlich aufgefallen, dass Namen, Kommentare und sprechende Bezeichnungen hilfreich gewesen wären - aber selbst wenn ich es jetzt nochmal bauen würde würde es vermutlich nicht viel besser werden.

Ich werde es jetzt noch so gut dokumentieren wie möglich und beim nächsten Projekt mache ich es von Anfang an besser.

[Zwenn]

Ich revidiere meine Aussage zu zwei Problemen. Es gibt nur ein Problem.
1. Dein Chef hat bereits einen Laien mit der Umsetzung beauftragt

Das ist nicht Deine Schuld. Schenk ihm ein T-Shirt mit der Aufschrift: "Kann man so machen, ist dann aber Scheiße"

:33:

[Käpt'n Blaubär]

Hallo Zwenn,

bezogen auf Deinen Post:

Max hat doch schon geschrieben, daß er der Einzige ist, der damit klarkommt und daß er das Ganze
ja auch zusammengeschustert hat. Aber was macht Dich so sicher, daß der Chef der Schuldige ist?
Ich denke eher, der Chef hat irgendwann mal den Auftrag gegeben, so ein Teil zu erarbeiten und dann
hat er irgendwann mal begriffen, daß wenn dieser Mitarbeiter aus welchen Gründen auch immer ausfällt,
der Laden irgendwann still stehen können wird.

Ist natürlich auch genau so nur eine Annahme wie Deine, aber wenn ich Max'ens Angaben analysiere,
dann betrachtet der Chef das Teil als Firmensoftware. Und egal, wie die Rechtslage sein mag, Max sollte
mit sich selber klarkommen und seinem Chef sagen, mache ich, oder ich mache es eben nicht.
Weinen, daß es so ist, wie es nun mal ist, nützt da eben auch nicht viel am Ergebnis.

[StrammerMax]

Ich habe auch nie behauptet, dass ich ein Profi bin.
Das ist das 2. Mal in meinem Leben, dass ich überhaupt mit VBA arbeite - und dafür finde ich wirklich erstaunlich, was ich in der Kürze der Zeit auf die Beine gestellt habe - das soll mir erst mal jemand ohne VBA Kenntnisse nachmachen.
Natürlich ist es meilenweit von perfekt entfernt - aber ich würde ohne arrogant klingen zu wollen behaupten, dass es im Unternehmen niemanden gibt der es besser könnte.

Das Tool gab es auch vorher schon, war aber 20 Jahre alt und sah dementsprechend aus (komplett ohne VBA).
Das Tool sollte überarbeitet werden und ein neues look and feel bekommen.

Natürlich hätte man das auch extern vergeben können... aber ihr wisst doch wie das läuft.. es darf nichts kosten - also muss es intern gemacht werden.

Das Tool ist essentiell und wird nahezu täglich genutzt. Insgesamt gibt es über 100 User.
Da sollte es natürlich auch funktionieren. Und das tut es auch --> solange niemand anfängt selbst daran rumzuspielen.

[Käpt'n Blaubär]

Hallo Max,

kein Mensch bestreitet hier Dein Können.
Und wie ich das Problem angehen würde, habe ich oben bereits geschrieben.

[StrammerMax]

Vielen Dank an alle für die hilfreichen Tipps.

Ich werde dann mal mein Bestes geben :)