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
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.