nicht angemeldet
Hellihello Vinzenz,
gemäß dem würde es dann in etwa so aussehen?
<?php
/**
- Short description for file
- Using an XSLTprocessor
- Long description for file (if any)...
// äh ja, hier kommt der meiner Meinung nach wichtigste Beitrag für eine gute
Dokumentation
Nun, in dem File jetzt steht ja nur die eine Klasse, was ja nicht selten der Fall ist, oder? Der Unterschied zwischen File-Desc. und Class-Desc. erschließt sich mit nicht unbedingt.
Meine Intention wäre zB so zu formulieren.
evtl File-Description:
With this Example File I try to demonstrate in HTML-AG
a) how to write a class in php
b) how to code correctly (s.a. Anmerkungen von dedlfix)
c) how to comment/document correctly (formally and reasonably)
evtl Class-Description:
Creating for demonstration and practical purspose a class, which transforms an xml-Dokument into an xhtml-Dokument using an xsl-stylesheet parsed by phps xslt-processor. The class reads xml and xsl from file and can either return the transformed xml as string or write it to a file.
// [...]
- Short description for class
- Process XSLT
- Long description for class (if any)...
// und hier.
>
> was Du da schreibst ist die formale Erfüllung irgendwelcher Vorschriften.
Jau, das war Anatz Teil 1.
> Gute, richtig gute Kommentare fangen dann erst an.
Jau, das kommt dann jetz, Inhalt in die Form packen.
> Beschränkung auf rein formale Erfüllung ist meiner Meinung nach in aller Regel schlechte Praxis, Kritik an der unbrauchbaren Dokumentation wird vom Autor damit erschlagen, dass die formalen Anforderungen doch erfüllt seien. Es sei doch Dokumentation vorhanden.
Schon klar.
>
> Der Benutzer, für den die Dokumentation gedacht sein sollte (denk an den Blogbeitrag), hat nichts (oder bestenfalls wenig) davon. Was da steht, ist das was Du in Deinem Titel bereits angesprochen hast: "Redundanzen mit Code". Für die IDE ist das gut. Der Benutzer von fremdem Code benötigt aber mehr, um den Code zu verstehen, richtig anzuwenden und gegebenenfalls modifizieren oder korrigieren zu können.
>
> Richtige und sinnvolle Dokumentation fängt meiner Meinung nach dort erst an.
> Leicht ist das übrigens nicht.
Wie aber unterscheidet sich die long-Description für den File von der long-description für die Klasse. Das o.g. ist ja eher die Beschreibung der Klasse.
Dank und Gruß,
Robert aka
[frankx](http://community.de.selfhtml.org/visitenkarten/view.php?key=82)
--
[tryin to](http://sauer-ernst.de) [multitain](http://multitain.de) - Globus = Planet != Welt