nicht angemeldet
Hallo Robert,
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
// [...]
- 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.
Gute, richtig gute Kommentare fangen dann erst an.
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.
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.
Freundliche Grüße
Vinzenz