Exception Handling.

[DGL-luke]

Aus der Sicht des gesunden Menschenverstandes. (Ich behaupte ja nicht, dass ich einen hätte )

Zu viel Redundanz bedeutet: Man braucht länger, bis man es verstanden hat, da man ja das unnütze Beiwerk mitlesen muss.
Zu wenig aber bedeutet, dass man evtl. nicht genügend information bekommt, nämlich die, die der autor vorausgesetzt und deswegen weggelassen hat.

Für den Benutzer sollte natürlich z.B. eine GUI so selbsterklärend sein, dass er keine Dokumentation braucht.
Aber auch hier gilt wieder: Mit zusätzlicher Komplexität - z.B. Funktionen, die nur selten benutzt werden - braucht man eine Dokumentation.

Code ist aber selten selbsterklärend - deshalb sollte sich der Programmierer schon die Mühe machen, hier und da oder zumindest bei mathematischen Operationen Kommentare einfließen zu lassen.

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.

[jbg]

Zitat von DGL-luke:

Wennin der JVCL aber "Verbindung erfolgreich geschlossen" eine Ausnahme darstellt, würde ich mir überlegen, warum ich diese komponenten benutze( )

Ganz einfach: Die JVCL macht sowas nicht. Das sind die Indy-Komponenten. Also bitte nicht ein OS-Projekt kritisieren, das dafür gar nichts kann.

Zitat:

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.

Nicht unbedingt. Man hat ja die Möglichkeit die Methoden in Gruppen zusammenzufassen, was ja wieder eine zusätzliche Information darstellt. So kann der Leser aus dem Zusammenhang der Methoden erkennen, was diese ungefähr machen. Aber um dieses "ungefähr" ganz zu erfassen, braucht es dann schon eine Doku, oder die Implementierung.

[Olli]

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 ...

[DGL-luke]

stimme euch zu, und habe den fehler korrigiert.

Zum unnützen Beiwerk:

Man muss sich einfach überlegen, welchen Wissensstand der durchschnittliche Leser der Dokumentation hat - desto geringer dieser, desto mehr Kontext braucht man. In einem Mathebuch für Gymnasiasten steht mehr drin als in einer Formelsammlung für Ingenieure. Und genau das meine ich damit.

[Olli]

Zitat von DGL-luke:

In einem Mathebuch für Gymnasiasten steht mehr drin als in einer Formelsammlung für Ingenieure. Und genau das meine ich damit.

Alles klar. In diesem Fall hast du natürlich recht. Leider kann man ja schlecht für alle Niveaus eine extra Doku schreiben. Daher gibt es Foren wie die DP