Zitat von
DGL-luke:
Zu viel Redundanz bedeutet: Man braucht länger, bis man es verstanden hat, da man ja das unnütze Beiwerk mitlesen muss.
Redundanz bedeutet erstmal Kontext. Wenn eine Dokumentation unnützes Beiwerk enthält, ist es ein Roman, keine Dokumentation. Das wäre sonst ein Oxymoron. Es mag sein, daß nicht alle Teile einer Dokumentation
für dich relevant sind, aber es geht ja nicht um dich allein.
Hier mal eine Information: Apfel, Pferd
Was will ich dir damit wohl sagen? All die schmückenden Worte sind redundant, aber nur mit denen kannst du überhaupt verstehen, was ich dir sagen will.
Zitat von
DGL-luke:
Für den Benutzer sollte natürlich z.B. eine
GUI so selbsterklärend sein, dass er keine Dokumentation braucht.
Wenn ich oben von Benutzer sprach, so war dies zB der Benutzer einer Klasse (also ein Programmierer wie auch du).
Zitat von
DGL-luke:
Aber auch hier gilt wieder: Mit zusätzlicher Komplexität - z.B. Funktionen, die nur selten benutzt werden - braucht man eine Dokumentation.
Angenommen du hast nur einen Header zu einer Funktion/Klasse - und diese Funktion oder Klasse ist tatsächlich nur eine Blackbox für dich, dann geht's eben tatsächlich nicht ohne Doku. Aber im Sinne der Wartbarkeit geht es IMO schon ab einer gewissen Größe des Projektes nicht mehr ohne Dokumentation. Wundert mich eigentlich, daß Hagen das nicht schon in die gemeinsame Arbeitsbasis ("Codestil") eingefaßt hatte.
Zitat von
DGL-luke:
Auch eine Klasse KANN selbsterklärend sein - sobald das ganze allerdings über ein paar Funktionen wie savetofile, draw und create hinausgeht, muss man eine Dokumentation zur Verfügung stellen.
Eine Klasse kann intuitiv sein, aber IMO nicht wirklich selbsterklärend. Denn wenn die Klasse über einen Container für "public" "properties" hinausgeht, dann tun irgendwelche Methoden irgendwas. Das braucht eine Doku.
Zitat von
jbg:
Aber um dieses "ungefähr" ganz zu erfassen, braucht es dann schon eine Doku, oder die Implementierung.
vollste Zustimmung! Das meinte ich mit intuitiv. Klar ist es intuitiv, wenn ich einer C++-Klasse einen überladenen operator+/operator+= mitgebe. Aber wie sind die Details der Speicherverwaltung etc. pp., auf was muß ich ggf. achten ...