Programm-/Code-Dokumentation? (Roter Faden)

[peacescorer]

Liebes Forum

Ich habe kein spezifisches (Code-)Problem, sondern brauche euren Rat...

Seit mehr als einem Jahr bin in an einer (mobilen) Excel-App dran, welche die Aufmasse in diversen Handwerksgattungen erheblich erleichtern soll... 
Ja, über ein Jahr...  - zu meiner Entschuldigung muss ich sagen, dass ich als Anfänger gestartet habe und meine Freizeit mit Frau und Kindern ohnehin knapp bemessen ist/war...

Diese " zeitlichen Unterbrüche" sind mittlerweile ein sehr störendes Problem geworden, da ich immer länger brauche, bis ich "wieder im Code drin bin"...

Ich habe mal den gesamten Code ausgedruckt und damit mein Büro tapeziert, aber da weder Einschübe noch die Farbmarkierungen wiedergegeben werden, hilft mir das überhaupt nichts...

Also hab ich mal angefangen, eine Art Dokumentation zu erstellen mit den verschiedenen Abläufen und den Prozeduren die jeweils zur Anwendung kommen. Aber ich weiss nicht genau, wie/wo und mit welchem Programm ich das umsetzen soll - Word eignet sich nicht wirklich, habe ich festgestellt. Ich bin mir sehr sicher, dass man vieles einfacher programmieren kann, aber ich habe mittlerweile wirklich Schwierigkeiten, meinem eigenen Code zu folgen (Vieles ist in Userformen, vieles in eigenen, angeschriebenen Modulen, auch gut auskommentiert, vieles wird als Argument übergeben, usw.).

Wie ist das bei euch Hardcore-Programmierern? 

Habt ihr bei komplexen Programmen sowas wie eine Dokumention/Leitfaden?
Wenn ja, mit welchem Programm visualisiert ihr diesen?
Was nehmt ihr wie auf?

Ich wäre um Rückmeldung sehr dankbar!

Schöne Grüsse an alle!

Christian

[Käpt'n Blaubär]

Hallo,

Ich bin mir sehr sicher, dass man vieles einfacher programmieren kann, aber ich habe mittlerweile wirklich Schwierigkeiten, meinem eigenen Code zu folgen (Vieles ist in Userformen, vieles in eigenen, angeschriebenen Modulen, auch gut auskommentiert, vieles wird als Argument übergeben, usw.).

VBA läßt sich auch in einzelnen Modulen programmieren. Dann wird alles plötzlich viel übersichtlicher.
Und wie Du ja schon selbst festgestellt hast, sinnvolle Einzüge machen das Ganze nochmal verständlicher.

Deine Frage nach Tools ist ziemlich einfach zu beantworten.
Du kannst im Forum nachsehen, ein Dir zusagendes Tool finden. Es steht regelmäßig ein Hinweis darunter,
wie das Tool heißt und wo es herkommt. Außerdem kannst Du bei der Suchmaschine Deines Vertrauens
anfragen. Wahrscheinlich schütten die Dich dann mit zielführenden Links zu.

Zur Dokumentationzwecken nutze ich, und ich nenne ausnahmsweise mal einen Namen, weil das Programm
so unglaublich vielseitig und leistungsfähig ist, und trotzdem kostenlos angeboten wird. Es heißt ScribblePapers

[Kuwer]

Hallo Christian,

schau Dir mal die Excel Code Jeanie an. Die kann noch mehr als Code in HTML umzuwandeln. Den Registrierungscode erhältst Du mittlerweile kostenlos hier.

Gruß Uwe

[losgehts]

Hallo,

das finde ich ein interessantes Thema und auch mich interessiert, wie ihr das macht.

Bei mir ist das so, dass ich keine großen Projekte, sondern kleine einzelne Exceldateien, mit nur einer sehr klar abgegrenzten Funktionalität (z.B. Berechnung einer Schraube) habe. Da hilft mir (m)ein klar strukturierter Code und meine Kommentare.
Diese Dateien entwickle ich in einer Art Projektverzeichnis (mit mehreren Unterordnern). Dort sind Literatur, die ich verwendet habe drin (im Code ist dann darauf verwiesen), alte Versionsstände, mindestens eine readme.txt, usw. enthalten.

Bei mir droht es in meinen eigenen allgemeinen AddIns unübersichtlich zu werden, die mit der Zeit wachsen und mich in meinem Alltag unterstützen sollen, aber nicht ein einziges, bestimmtes Ziel haben, sondern mehrere. Hier habe ich mir angewöhnt, jedes Modul und jede Userform direkt sprechend zu benennen. Auch bemerke ich, dass ich mir zunehmend mehr Gedanken beim Programmieren über die Namen von Funktionen und einzelnen Makros mache, was mir ebenfalls sehr hilft. Hat man ein Modul geöffnet, kann man ja rechts im Dropdown alle enthaltenen Funktionen sehen.
Wie der Käpt'n es auch empfiehlt, bemerke ich, dass ich zunehmend mehr Module benutze als früher.

Zu Beginn eines Moduls (und evtl. auch bei einzelnen Funktionen) schreibe ich oft einen mehr oder weniger langen Kommentar, der erklärt, was das Modul beinhaltet, ob es Dinge gibt, die noch nicht implementiert sind, Bugs halte ich da fest, wesentliche Entwicklungsschritte... kleine ASCII-Skizze bei Geometrien, ...

Ich verwende keine zusätzliche Software.

Aber wie gesagt: eine einzelne Datei (außer meinen allgemeinen AddIns) enthält bei mir in der Regel nicht mehr als 2000 Codzeilen und das finde ich noch recht übersichtlich.

In anderen Programmiersprachen arbeite ich auch mit Klassen, da kommt es schon mal vor, dass ich mir vor/während dem Programmieren auf einem Zettel handschriftlich ein paar Skizzen mache (UML ähnlich). Die habe ich früher immer danach weggeworfen. Jetzt scanne ich sie einfach ein und lege sie im Projektordner ab - habe damit aber noch keine Erfahrung.

Grüße, Ulrich

[Case]

Hallo, :19:

das hängt weitestgehend davon ab, ob du mehrere größere Projekte hast bzw. noch planst. Wenn das so ist, kommst du um eine vernünftige Dokumentation eigentlich nicht herum. Nun ist das für jeden natürlich anders gelagert. Was für den einen schon ein riesen Projekt ist, ist für den anderen eher eine Pausenbeschäftigung. Da kommt es nun auch nicht auf die Anzahl der Codezeilen an (weder viele, noch wenige).

Ich arbeite seit vielen Jahren mit den MZ-Tools (die leider nicht mehr kostenlos sind - früher waren sie das zumindest für VBA).

Dort kannst Du eine HTML- oder XML Dokumentation deines Codes erstellen. Die beinhaltet alles, was du brauchst.

Du kannst dir Codestatistiken ausgeben lassen. Codeteile per Tastendruck einfügen. Definierte Header im Code einfügen. Fehlerbehandlung automatisch einfügen. Und, und, und...

Hier mal ein Ausschnitt: :21:

externer Link entfernt

[maninweb]

Hallo,

was mich betrifft, schreibe ich meinen Code anhand einer eigenen Konvention möglichst in der Art, dass dieser wie ein Text zu lesen ist.
Zum Beispiel bei der Benennung von Klassen, Modulen, Funktionen, Prozeduren oder Tabellen. Macht dann zwar häufig mehr Tipparbeit,
aber für mich lohnt es sich und ermöglicht es mir, mich auch nach Jahren recht schnell wieder im Code reinzufinden, da ich mich ja
nunmal an die Konvention gewöhnt habe. Ausnahmen gibt's immer, z.B. bei sehr komplexen Berechnungen, wo ich dann schon mal
was länger brauche, mich wieder reinzufinden. Das Ganze, also die Art Code zu schreiben, ist auch über die Jahre gewachsen.

Wichtig ist für mich auch der strukturelle Aufbau. Da ich aus OOP nahen Sprachen (z.B. C++) zu VBA gekommen bin, ist das Design
einzelner Bestandteile (Module/Klassen/Events) für mich essentiell. Hierbei orientiere ich mich dann schon an OOP-Methoden
und nehme dann auch durchaus Papier und Stift in die Hand, um die einzelnen Aufgaben der Module/Klassen zu skizzieren.

Für mich selber dokumentiere ich nicht. Für Kunden schon, dann natürlich kostenpflichtig. Und dies meist in Word bzw. PDF und dann
detaillierter die verwendete Struktur & Verfahren, weniger den Code selbst bzw. nur relevante Ausschnitte. Ich bin da der Meinung,
wenn ein Nachfolger z.B. den Code übernehmen möchte/müsste, sollte dieser auch ein entsprechendes Wissen von VBA haben.

Gruß

[Zwenn]

Hallo,

wie den Beiträgen der anderen schon zu entnehmen ist, ist eine saubere Struktur Deines Projektes essentiell. Ich kenne es aber auch selbst, wenn man 'nur mal schnell' noch an der einen oder anderen Stelle was einfügen oder ändern will, dann kann das ziemlich nach hinten losgehen, wenn man seinen Code 3 Wochen später wieder hervorholt und sich denkt: 'Was habe ich mir denn dabei gedacht?'

Für größere Sachen mache ich mir vorher Gedanken und skizziere die Bestandteile. Das Skizzieren kann dabei die Form haben, die Dir am ehesten zusagt. Mindmaps sind geeignet, um Zusammenhänge der einzelnen Bestandteile herauszuarbeiten. Wenn es eine Nummer größer bzw. universell einsetzbar sein soll, nimmt man für diese Aufgabe UML (Unified Modelling Language).
https://de.wikipedia.org/wiki/Unified_Modeling_Language

Auch Text ist gut geeignet. Man kann einfach formulieren, was man eigentlich programmieren will. Bei diesem in Worte fassen merkt man dann meistens sehr schnell, dass es mit 'einfach' nicht allzuweit her ist. Das ist aber gut so, denn wenn man einfach mal anfängt zu programmieren, ohne sich vorher im Klaren darüber zu sein, wie man das Ziel erreicht, auf das man hin arbeitet, kommt dabei in der Regel etwas raus, was man nachträglich selber nur noch schwer überschauen kann und was für andere Entwickler eine Zumutung ist. Letzteres natürlich nur, wenn die Gefahr besteht, dass von Dir entwickelter Code mal in andere Hände übergeht oder Dir jemand bei der Fehlersuche helfen soll.

Beim Texten nicht nur das Ziel formulieren, sondern vor allem den Weg, wie man es erreichen will. Das ist dann das berühmte zerlegen des Gesamtproblems in Teilprobleme, die sich für sich lösen lassen und am Ende so zusammen arbeiten, dass sie das Ganze bilden. Man könnte auch direkt sagen, bei diesem Vorgang planst Du Deine Module und Funktionen. Du kommst dabei auch zwangsläufig darauf, dass der rein strukturierte Ansatz nicht reicht, sondern Du OOP (Objekt Orientierte Programmierung) brauchst. Unter VBA liest man oft von Klassenprogrammierung, was aber OOP ist.

Ausserhalb des Editors selbst dokumentiere ich ansonsten eigentlich nichts. Dafür halte ich mich an Konventionen, die einem als Anfänger vor allem lästig erscheinen. Beim Debuggen, dem wieder Einfinden in den Code und nicht zuletzt auch dem nachvollziehen, was ein bestimmter Codeabschnitt eigentlich macht, sind diese Konventionen aber sehr hilfreich.

Eine kleine Übersicht dazu:
- Voneinander unabhängige Bereiche des Projektes kommen in unterschiedliche Module
- Allgemeine Methoden, die von verschiedenen Modulen benötigt werden, kommen in ein eigenes Modul
- Werte die feststehen als Konstanten definieren. Das ist übersichtlicher, weil die Wertzuweisung in der gleichen Zeile stattfindet
- Prozeduren, Konstanten, Variablen bekommen sprechende Namen. Davon bin ich ein großer Fan, weil es den Code viel lesbarer macht
- Datentypen haben einen Sinn, deshalb setzt man immer den Datentyp ein, der für das Gewünschte ausreicht
- Kommentiere Deinen Quellcode ausgiebig. Wenn Dein Ausarbeitungstext es hergibt, kannst Du den Code quasi zwischen die Zeilen schreiben
- Immer die gleiche Schreibweise für eigene Bezeichner verwenden. Z.B. Prozedurnamen beginnen immer mit einem Großbuchstaben, Variablen klein
- Alle Variablen werden lokal vereinbart (Bitte an dieser Stelle keinen Glaubenskrieg über globale Variablen. Wer will, soll sie verwenden)
- Es werden keine Sprungbefehle verwendet
- Die Fehlerbehandlung nur einsetzen, wenn sie notwendig ist und nur in den benötigten Grenzen

Das ist meine herangehensweise. Achja, ganz oben in jedes Modul gehören die beiden Worte 'Option Explicit', um die Variablendeklaration zu erzwingen.

Viele Grüße,

Zwenn

[schauan]

Hallöchen,

Achja, ganz oben in jedes Modul gehören die beiden Worte 'Option Explicit', um die Variablendeklaration zu erzwingen.

Man kann auch über den Einsatz von "Option Private Module" nachdenken. Das spart zuweilen einen mehr oder weniger massiven Einsatz von Private vor Sub .

[Zwenn]

Hallöchen,

Man kann auch über den Einsatz von "Option Private Module" nachdenken. Das spart zuweilen einen mehr oder weniger massiven Einsatz von Private vor Sub .

Moin,

ja, könnte man. Ich habe mich bei meiner Aufzählung aber auf die Dinge beschränkt, zu denen man keine Entscheidung treffen muss, ob man sie grade einsetzen sollte oder nicht. Es sind alles Dinge, die (für mich) generell gelten :19: