mike-pretzlaw
Mitglied
Was denkt ihr über Code dokumentation? Ich meine nicht die Einzeiler, welche mitten im Code den nächsten Block erklären, sondern über die Funktionen, Methoden, Klassen und Dateien. Klar das meiste liefert die IDE selbst, aber wie sehr führt ihr das fort?
Im Laufe der Zeit hat sich folgendes bei mir manifestiert:
Im Kopf der Datei steht nur rudimentär, was dort enthalten ist.
Also einen Satz je Klasse und mehr nicht. Vielleicht noch ein paar Doc-Tags aber das war es dann auch.
Die Doku über der Klasse enthält keine Beispiele, sondern die benötigten Mittel.
Wie zum Beispiel SQL-Statements für eine Tabelle die von einem Model benutzt wird. Aber Beispiele und Snippets blähen die Datei unnötig auf. Sicherlich ist dem Interpreter das egal, aber solange der Dokumentations-Generierer auch über andere Wege Snippets einbringen kann finde ich nicht, dass sie in Kommentare gehören. Nur für eine Klasse erst einmal 100 Zeilen Kommentare zu lesen, ist auf Dauer echt nervig.
Bei den Konstanten und Variablen wird in einem Satz Nutzen und Inhalt erklärt.
Hier frage ich mich ob noch gezeigt werden sollte, wo es eventuell genutzt wird aber insbesondere das halte ich für überflüssig.
Bei Methoden und Funktionen gibt es keine Beispiele, die Signatur muss für sich selbst sprechen!
Hier nehme ich auch noch gern @since hinzu, aber pflegt jemand @version oder @author auf solch einer Mikro-Ebene? Vor allem in Hinblick auf CVS.
Würd mich echt interessieren was so eure Workflows für das Dokumentieren sind und was ihr alles in die Doku einbringt. Auch womit ihr sie erstellt und wie vollständig das ganze dann ist.
Im Laufe der Zeit hat sich folgendes bei mir manifestiert:
Im Kopf der Datei steht nur rudimentär, was dort enthalten ist.
Also einen Satz je Klasse und mehr nicht. Vielleicht noch ein paar Doc-Tags aber das war es dann auch.
Die Doku über der Klasse enthält keine Beispiele, sondern die benötigten Mittel.
Wie zum Beispiel SQL-Statements für eine Tabelle die von einem Model benutzt wird. Aber Beispiele und Snippets blähen die Datei unnötig auf. Sicherlich ist dem Interpreter das egal, aber solange der Dokumentations-Generierer auch über andere Wege Snippets einbringen kann finde ich nicht, dass sie in Kommentare gehören. Nur für eine Klasse erst einmal 100 Zeilen Kommentare zu lesen, ist auf Dauer echt nervig.
PHP:
/**
* Die Klasse Foo macht Bar.
*
* Mit der Klasse Foo kann insbesondere ...,
* um ...
* damit ....
* Dazu benötigt sie diese Tabelle:
* CREATE TABLE IF NOT EXISTS Foo
...
*/
Bei den Konstanten und Variablen wird in einem Satz Nutzen und Inhalt erklärt.
PHP:
/**
* Wert für den Sinn des Lebens
* @var int
*/
const BAR = 42;
Hier frage ich mich ob noch gezeigt werden sollte, wo es eventuell genutzt wird aber insbesondere das halte ich für überflüssig.
Bei Methoden und Funktionen gibt es keine Beispiele, die Signatur muss für sich selbst sprechen!
PHP:
/**
* Baz löscht unnötigen Kram
*
* @var string $name Der Name der Sache
* @var int $anzahl Die Anzahl der zu löschenden Sachen
* @var bool $aufErfolgtesten Optional: Prüft ob alles glatt gelaufen ist (default: false)
*
* @return int Sinn des Lebens
*/
function baz($name, $anzahl, $aufErfolgTesten) {
return BAR;
}
Hier nehme ich auch noch gern @since hinzu, aber pflegt jemand @version oder @author auf solch einer Mikro-Ebene? Vor allem in Hinblick auf CVS.
Würd mich echt interessieren was so eure Workflows für das Dokumentieren sind und was ihr alles in die Doku einbringt. Auch womit ihr sie erstellt und wie vollständig das ganze dann ist.