Was muss dokumentiert werden?

    Hallo Zusammen.

    Frage an die Profis von Euch: Während ihr eine Website erstellt bzw. verschiedene PHP-Scripte / -Seiten schreibt, dokumentiert ihr etwas? Ich meine, schreibt ihr euch alle Session-Variablen, Variablen, usw. auf? ... was welche Funktion oder Variable an welcher Stelle macht usw.? Was dokumentiert ihr? Ich meine nicht in das Script selbst, sondern auf Papier oder im Texteditor.

    Ich programmiere seit einigen Monaten an einer sehr großen Website und darin gibt es natürlich viele Variablen und Session-Variablen. Ich möchte nicht in die Verlegenheit kommen dass ich mal an verschiedenen Stellen zwei Mal die gleiche Variable verwende, die sich irgendwann vielleicht mal "beißen". DANN den Fehler zu finden ist ein Alptraum denke ich.

    Ich hoffe ihr wisst was ich meine und würde gerne eure Erfahrung wissen.
    Danke!

    UWE

    Einmal editiert, zuletzt von Ugenmeister (7. Mai 2013 um 17:39)

    Zitat von Ugenmeister

    Ich meine nicht in das Script selbst, sondern auf Papier oder im Texteditor.


    Das mache ich nie! Im Quellcode Kommentare schreiben reicht mir.

    Session- und Variablennamen zu dokumentieren ist unnötig. Wenn da Überschneidungsgefahr besteht hast du ein schlechtes Softwaredesign bzw. eine schlechte Namensgebung für Variablen. Ein so umfangreiches Projekt, dass da Überschneidungsgefahr besteht sollte Objektorientiert umgesetzt sein, so dass sich diese Frage kaum bis gar nicht stellt. In Kombination mit aussagekräftigen Variablennamen erübrigt sie sich komplett.
    Nichts desto trotz macht bei einem umfangreichen Projekt das professionell umgesetzt wird die tatsächliche Programmierung ca. 50% aus, der Rest ist Dokumentation. Und ein großer Teil der Dokumentation sollte stattfinden bevor überhaupt eine Zeile Code geschrieben wird. Diese Dokumentationen haben aber wenig mit Variablennamen zu tun, da geht es um Struktur und Funktionalitäten der Software.

    "Programming today is a race between software engineers
    striving to build bigger and better idiot-proof programs,
    and the universe trying to build bigger and better idiots.
    So far, the universe is winning."
    Rick Cook

    und für den fall von ausnahmeprogrammierungen, die eigentlich auch nicht sein sollten, aber in der praxis doch mal vorkommen, sollten diese auch notiert werden. ebenso funktionen die essentiell sind.

    Also generell würde ich mal sagen ist das "interface" zu Dokumentieren Pflicht. D.h. alle Funktionen die du tatäschlich benutzt, im OOP-Bereich die öffentlichen (public) Methoden. Methoden, die nur intern benutzt werden (private) kann man auch undokumentiert lassen, wenn es sich um eine in sich geschlossene Komponente (Klasse) handelt.