Jetzt mal ehrlich: Wer dokumentiert seinen Code vollständig?

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.

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.
 

Akeshihiro

Erfahrenes Mitglied
Author und Version gibt es bei uns gar nicht. Wieso? Ganz einfach. Es arbeitet nie nur eine Person an einem Code, sondern immer mehrere. Refactorings wirken sich oft auf etliche Dateien aus, wer soll sowas nachpflegen und überwachen. Wenn man wissen will, wer was verzapft hat, wird der Log des VCS/SCM genommen, aber soweit kommt es eigentlich auch nicht, denn es ist schon vorher klar, wer Schuld hat.

File-Kommentare haben wir bei uns auch nicht, wozu? Steht eh nur das Copyright drin und lauter unnützes Zeug. Wichtig sind dagegen aber die JavaDocs zu den Klassen, denn die beschreiben, was der Sinn der Klasse ist. Das ist öfter mal auch etwas ausführlicher, auch mit Beispielen. Dafür geraten die Methoden dann aber meist eher kurz. Das liegt aber daran, dass immer schon durch den Methodennamen klar ist, was da passiert und wenn nicht, ist der Methodenname falsch und muss angepasst werden. Wir programmieren so, dass man den Code lesen kann. Gibt es einen unklaren Code-Block, wird dieser in eine Methode mit entsprechendem Namen ausgelagert. So entfällt ein unnötiger Kommentar und der Anweisungsblock ist nochmal kürzer und übersichtlicher. Die Hauptdokumentation stellen bei uns aber eigentlich die Tests dar. Diese testen verschiedene Szenarien und dokumentieren die Klassen und Methoden somit eigentlich am besten. Daneben haben wir noch eine Entwicklerdokumentation, die wird entsprechend immer nachgepflegt.

Fakt ist, ich werde nicht für unnütze Tests oder eine übertriebene Dokumentation mit zu vielen Details bezahlt, sondern für die Entwicklung einer Software. Der Code ist lesbar, klar strukturiert, es gibt ausführliche JavaDocs zu den Klassen, bei Methoden mit besonderer Wichtigkeit und daneben noch Tests, die testen, was sie sollen und nicht jede noch so perverse Situation, die einem irgendwie einfallen und theoretisch vielleicht auftreten könnte. Es wird also das erwartete Verhalten getestet und bei Bugs sichergestellt, dass das nicht nochmal auftreten kann. Damit ist eigentlich immer klar, was wie und wofür gedacht und anzuwenden ist ohne sich mit irgendwelchem Beiwerk beschäftigen zu müssen.
 

timestamp

Mitglied Käsekuchen
Ich halte es bei aussagekräftigen Variablen/Konstanten/Methoden/Klassen Bezeichnungen.
Alleine dadurch spart man sich (wie oben schon genannt) viele Kommentare.
Aus
Java:
public double abcd(double arg1, double arg2){
  return Math.sqrt(arg1*arg1+arg2*arg2);
}
wird
Java:
public double pythagoras(double a, double b){
  return Math.sqrt(a*a + b*b);
}
Dokumentationen/Kommentare nutze ich bei manchen Rechenschritten, die sonst schnell unklar werden können, ober bei "magic numbers", wobei ich die meisten magic numbers durch Konstanten mit klaren Namen ersetze.
 

alxy

Erfahrenes Mitglied
ICH = (Hobbyentwickler, Schüler) dokumentiere normalerweise garnicht, da ich Klassen nicht selber schreibe, sondern bestehende benutze (Frameworks). Es gibt in der Webentwicklung ja generell wenige Anwendungsgebiete, für die noch keine Klasse entwickelt wurde. Und in meinen Controllern, Models und Views ist es doch relativ sinnlos zu dokumentieren - oder sehe ich das falsch? Sollte ich mal selber eine Klasse schreiben (zB ein Modul für ein framework), würde ich allerdings wahrscheinlich ähnlich vorgehen wie der TE.
 

chmee

verstaubtes inventar
Premium-User
Große Doku? Nein. Aber die Projekte sind für eine OneManShow dann doch größer/unübersichtlicher geworden und um mir selbst (zB 1 Jahr später) eine Hilfe zu geben, werden, wie yaslaw (*Sorry* timestamp) es anspricht sinnvolle Funktions- und Variablennamen benutzt und idR vor jeder Funktion eine Kurzbeschreibung (ein bis Zweizeiler) - soweit nötig.

Letztlich hab nur ich mit meinem Code zu tun, ergo ist eine reichhaltige Doku unnötig, aber im Hinblick auf die Zeit dennoch sinnvoll.