Guten Morgen,
ich programmiere eine Web-Anwendung (LAMP/MVC) und überlege, wie ich das
Ganze außerhalb des Quellcodes so dokumentieren kann, dass ich neben der
Bedeutung von Funktionsblöcken auch die Bedeutung von bestimmten Zeilen
dokumentieren kann? Es geht nicht nur um PHP-Kommentare, sondern auch um
HTML- und Javascript-Kommentare in den View-Dateien.
Darüber hinaus sollten auch Abhängigkeiten mit anderen Funktionsblöcken
erkennbar sein, denn ich habe oft das Problem, dass Funktionen geändert
oder erweitert werden müssen und dann andere Bereiche an anderen Stellen
ebenfalls angepasst werden müssen.
Gibt es Hilfsmittel für das Kommentieren außerhalb des Quellcodes und
falls ja, wie stellt man sicher, dass bei Änderungen am Quellcode nicht
das Anpassen der dazugehörigen außerhalb gespeicherten Kommentare
vergessen wird?
Gibt es Hilfsmittel für die Darstellung der Abhängigkeiten/Beziehungen
zwischen verschiedenen Funktionen?
Das Betriebssystem für die Entwicklungsumgebung ist erstmal Nebensache,
mich interessieren mehr die grundsätzlichen Lösungsansätze in so einem
Fall.
Schöne Grüße
Georg
Da hast du dier das schwierigste aller Themen vorgenommen.
Bisher sind alle zu dem Ergebniss gekommen -- das muss man umgekehrt
anpacken. Die Abhängigkeiten überschaubarer anlegen. Nur leider waren
HTML, Javascript und Webserver ein gewaltiger Rückschritt gegenüber den
prähistorischen Client-Server Konzepten. Und die modernen Webtechniken
verursachen mehr Unübersichlichkeit, als sie lösen.
Ob es Hilfsmittel gibt? Würden diese Hilfsmittel funktionieren, dann
würden wir nicht mit diesen Krücken die Doku aus den Kommentaren
generieren.
Nach allem, was ich bisher heraus gefunden habe, gibt es nur unzählige
Scharlatane. Die behaupten, deren Firma hätte eine Lösung.
Da braucht es jemanden wie Alan Kay. Jemanden, der alle unzulänglichen
Lösungsansätze ignoriert und mit irrsinnig erscheinenden Ideen neue
Konzepte ausarbeitet.
Welchen Sinn macht es, eine "einzelne Zeile" zu kommentieren, wenn das
ausserhalb, also nicht direkt neben der Zeile erfolgt ? Es wird sowieso
niemand lesen. Doku liest eh keiner. Eine leicht verständliche Struktur
(d.h. nicht überall ungenutzte Features für zukünftige Erweiterungen die
dann sowieso ungenutzt bleiben) mit quasi selbsterklärenden Namen und
nur ein Überblicksdokument in dem ggf. zur Konfiguration wichtige
Stellen erklärt werden sollte reichen.
Georg schrieb:> wie ich das Ganze außerhalb des Quellcodes so dokumentieren kann, dass> ich neben der Bedeutung von Funktionsblöcken auch die Bedeutung von> bestimmten Zeilen dokumentieren kann?
Die Kommentare und weiteres erstellst Du als Bestandteil im Quellcode,
und mit einem Tool wie Doxygen kannst Du daraus dann automatisiert
Dokumentation erzeugen, die außerhalb des Quellcodes liegt.
Inwiefern das bei Ein-Zeilen-Kommentaren sinnvoll ist, bleibt Dir
überlassen.
Georg schrieb:> ich programmiere eine Web-Anwendung (LAMP/MVC) und überlege, wie ich das> Ganze außerhalb des Quellcodes so dokumentieren kann, dass ich neben der> Bedeutung von Funktionsblöcken auch die Bedeutung von bestimmten Zeilen> dokumentieren kann? Es geht nicht nur um PHP-Kommentare, sondern auch um> HTML- und Javascript-Kommentare in den View-Dateien.
Was spricht dagegen, die Kommentare im HTML- bzw. JS-Code zu packen? Da
gehören sie hin. Das ist der einzige Ort, an dem sie gelesen werden?
Wenn Du Sorgen hast, dass der Nutzer der Webseite diese Kommentare zu
gesicht bekommt, dann würde ich die Kommentare automatisch entfernen.
mfg Torsten
>Was spricht dagegen...
In der Praxis funktioniert es nicht. Man muss sich die Kommentare aus
Quelltext, Besprechungsprotokollen, Versionsverwaltung und Wikis
zusammensuchen. Und was wirklich gemacht wurde, erfährt man zufällig in
der Kantine.
Tools, die dieses Problem lösen sollen, machen es nur noch schlimmer.
Alle 3 Jahre ersetzt irgend ein Typ aus dem Wasserkopf das nicht
funktionierende Tool durch ein anderes nicht funktionierendes Tool. Die
alte Doku geht dabei verloren.
Ich dokumentiere alles im Quelltext.
Dann sind alle wichtigen Dinge an einer Stelle vereint. Nichts geht
verloren, und die Mitprogrammierer haben auch gleich alle Infos.
Für das Erstellen einer Übersicht verwende ich Doxygen. Das extrahiert
Informationen aus Programmkommentaren und baut eine Funktions und
Modulübersicht. Ich nehme das für C++ und C. Auch für VHDL hab ich das
mal benutzt. Es ist für verschiedene Programmiersprachen verfügbar.
http://www.stack.nl/~dimitri/doxygen/index.html
>Dann sind alle wichtigen Dinge...
In den meisten Betrieben werden die wichtigen Entscheidungen ausserhalb
der Programmierung getroffen.
Du fragst dich: "Warum hat dein Vorgänger so ein unsinniges Konzept
implementiert?" Dann stellt sich heraus, das hatte eine Knalltüte beim
Kunden erfunden. Inzwischen haben die ihn rausgeworfen und du kannst das
Problem sinnvoll angehen.
Von solchen Entscheidungen findest du im Quelltext nichts. Und mit dem
Scrum ist es noch schlimmer geworden. Die Programmierer kennen die
Gründe überhaupt nicht mehr. Die bekommen nur eine Story, die sie
eintippen sollen.
Georg schrieb:> Gibt es Hilfsmittel für das Kommentieren außerhalb des Quellcodes und> falls ja, wie stellt man sicher, dass bei Änderungen am Quellcode nicht> das Anpassen der dazugehörigen außerhalb gespeicherten Kommentare> vergessen wird?
Hallo Georg,
Unter dem Begriff "Literate Programming" gibt es solche Hilfsmittel.
Die gehen aber wahrscheinlich über das hinaus, was Du suchst.
"Literate Programming" stellt die Dokumentation quasi über den
eigentlichen Quelltext. Meistens muss der Ursprungstext erst
durch ein Skript oder Programm geschickt werden, um den
eigentlichen Quelltext zu erhalten, den man dann compilieren kann.
Der Nachteil ist, dass man ohne das "Literate Programming" Tool
nicht direkt compilieren kann.
Literate Programming vom "master himself"
http://literateprogramming.com/
Tools nicht nur für C, sondern quasi sprachunabhängig:
noweb
http://www.cs.tufts.edu/~nr/noweb/
funnelweb (scheinbar seit 1999 nicht mehr aktualisiert)
http://www.ross.net/funnelweb/index.shtml
Wikipedia
https://de.wikipedia.org/wiki/Literate_programming
Noch einer schrieb:> In den meisten Betrieben werden die wichtigen Entscheidungen ausserhalb> der Programmierung getroffen.
Dass es die meisten Betriebe sind, ist jetzt geschätzt oder gibt es da
Studien?
> Von solchen Entscheidungen findest du im Quelltext nichts. Und mit dem> Scrum ist es noch schlimmer geworden. Die Programmierer kennen die> Gründe überhaupt nicht mehr. Die bekommen nur eine Story, die sie> eintippen sollen.
Dir ist aber schon klar, dass Du den Arbeitgeber auch wechseln kannst?
Ansonsten ist "Ausbildung & Beruf", glaube ich das richtige Forum für
"Alle Doof. Keiner ausser mir hat Ahnung. Würde doch entlich mal jemand
auf mich hören"-Themen. Hier ging es doch um die Dokumentation von
Quellcode!
MaWin schrieb:> Welchen Sinn macht es, eine "einzelne Zeile" zu kommentieren, wenn das> ausserhalb, also nicht direkt neben der Zeile erfolgt ?
Es geht zum einen um Übersichtlichkeit. Bei meinem aktuellen Projekt
werden wirklich sehr umfangreiche und komplizierte Vorgänge
implementiert, die teilweise dann auch umfangreicher Erläuterungen
bedürfen, damit andere das nachvollziehen und den Code ändern können.
Bevor ich da für jede Funktion einen Aufsatz schreibe, ist es
sinnvoller, den Sinn einzelner Zeilen direkt zu erklären. Mit dieser
Masse an Kommentaren würde ich die Übersichtlichkeit des Codes jedoch
drastisch reduzieren.
Zum anderen sind - wie es "Noch einer" völlig zutreffend bemerkte - oft
so etwas wie Meta-Informationen notwendig, die im Quelltext nichts zu
suchen haben oder die selbst mit ASCII-Art nur schwer illustrierbar
sind. Da wäre ein übergeordnetes System schon schön, in dem man
Kommentare mit bidirektionalem Quelltext-Bezug definieren kann, die im
Quelltext selbst z.B. nur als verlinkte neutrale Fußnoten auffallen.
Vielen Dank an euch alle für die Tipps soweit.
Vele Grüße
Georg
Die Angabe einer E-Mail-Adresse ist freiwillig. Wenn Sie automatisch per E-Mail über Antworten auf Ihren Beitrag informiert werden möchten, melden Sie sich bitte an.
Wichtige Regeln - erst lesen, dann posten!
Groß- und Kleinschreibung verwenden
Längeren Sourcecode nicht im Text einfügen, sondern als Dateianhang
Announcement: there is an English version of this forum on 
Thread beobachten
Seitenaufteilung abschalten