mikrocontroller.net

Forum: PC-Programmierung Sourcecode für Web-Projekt "dokumentieren"


Autor: Georg (Gast)
Datum:

Bewertung
1 lesenswert
nicht lesenswert
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

Autor: Noch einer (Gast)
Datum:

Bewertung
1 lesenswert
nicht lesenswert
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.

Autor: MaWin (Gast)
Datum:

Bewertung
1 lesenswert
nicht lesenswert
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.

Autor: Rufus Τ. F. (rufus) (Moderator) Benutzerseite
Datum:

Bewertung
2 lesenswert
nicht lesenswert
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.

Autor: Torsten R. (Firma: robitzki.de) (torstenrobitzki)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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

Autor: Noch einer (Gast)
Datum:

Bewertung
-1 lesenswert
nicht lesenswert
>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.

Autor: PittyJ (Gast)
Datum:

Bewertung
1 lesenswert
nicht lesenswert
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

Autor: Noch einer (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
>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.

Autor: Alexander S. (alesi)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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

Autor: Torsten R. (Firma: robitzki.de) (torstenrobitzki)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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!

Autor: Georg (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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

Antwort schreiben

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

Formatierung (mehr Informationen...)

  • [c]C-Code[/c]
  • [avrasm]AVR-Assembler-Code[/avrasm]
  • [code]Code in anderen Sprachen, ASCII-Zeichnungen[/code]
  • [math]Formel in LaTeX-Syntax[/math]
  • [[Titel]] - Link zu Artikel
  • Verweis auf anderen Beitrag einfügen: Rechtsklick auf Beitragstitel,
    "Adresse kopieren", und in den Text einfügen




Bild automatisch verkleinern, falls nötig
Bitte das JPG-Format nur für Fotos und Scans verwenden!
Zeichnungen und Screenshots im PNG- oder
GIF-Format hochladen. Siehe Bildformate.
Hinweis: der ursprüngliche Beitrag ist mehr als 6 Monate alt.
Bitte hier nur auf die ursprüngliche Frage antworten,
für neue Fragen einen neuen Beitrag erstellen.

Mit dem Abschicken bestätigst du, die Nutzungsbedingungen anzuerkennen.