Aber es gibt Möglichkeiten: Schreib ne schöne, neue Methode und mach die alte deprecated.
Das ist eine gute Idee, werde ich mal hier im Team anregen.
Zitat:
Trotzdem würde ich auch bei einer eindeutig benamten Funktion, mit eindeutig benamten Parametern, eine Dokumentation erwarten.
Auch wenn in der Dokumentation "nur" in Prosa das steht, was man beim Namen der Funktion erwarten würde.
Einfache Frage: Warum?
Es kommt immer darauf an, für wen die Dokumentation ist.
Dokumentation ist aufwendig, also möchte man nicht für jede Zielgruppe eine eigene Doku schreiben.
Man erstellt Doku, die von mehreren Zielgruppen verwendet werden kann.
z.B. von Prüfern der externen Revision
Die Dokumentation einer
API muss (z.B. für die Prüfer) verschiedene Kriterien erfüllen.
z.B. wird Erwartet, dass Funktionsänderungen in den Klassen / Methoden mit Datum und Version beschrieben werden.
(ab v2.0.1 (01.01.2013) wird nicht mehr kaufmännisch, sondern mathematisch gerundet.)
Zitat:
Ich bin auch Fan von Änderungshistorien.
- Kommentare sind keine schlechte Versionsverwaltung. Kommentare sind *etwas anderes*. Da die selben Infos rein zu packen, macht keinen Sinn.
Da gebe ich dir Recht.
Aber, wenn eine Funktion (nennen wir sie GetDefaultColor) eine Farbe zurückgibt (z.B. Blau) und das auch dokumentiert ist, sich ändert und nun eine andere Farbe zurückgibt (z.B. Grün), dann würde ich mir in der Doku folgendes wünschen:
Code:
...gibt die Farbe Blau zurück.
...ab v2.0 gibt die Funktion die Farbe Grün zurück.
Das macht vor allem dann Sinn, wenn aus Gründen der Wartbarkeit nur eine (aktuelle) Doku vorgehalten wird, die
API aber leider auch in älteren Versionen verwendet wird.
- "gehört für mich einfach rein" ist kein Grund. Wenn ich bemerke, dass ich für eine Meinung keine Gründe habe, stelle ich diese in Frage. Ich kann das nur empfehlen, denn es ist augenöffnend.
Auch hier gebe ich Dir Recht.
Ich bin auch kein Fan von "Warum?" -> "Das haben wir schon immer so gemacht!"
Warum sage ich eigentlich immer "sinnvoll sein kann"? Ganz einfach: Wie in meinem ersten Beitrag hier im Thread geschrieben, kommt es immer auf die Stakeholder drauf an. Doku machen wir aus einem Grund. Nämlich, dass sie gelesen wird. Doku macht Arbeit. Arbeit zu schreiben, Arbeit zu pflegen und ja, auch Arbeit zu lesen. Wenn ich jetzt Doku habe, die keinen Mehrwert bietet, sondern genauso schlau bin, nachdem ich sie gelsenen habe, wie zuvor, hätte ich mir gar nicht erst die Mühe machen müssen, sie zu lesen. Es ist frustrierend, Doku zu lesen, die keinen Mehrwert bietet und nich frustrierender, wenn man sich vor Augen hält, dass jemand Zeit darin investiert hat, mir dadurch Zeit zu rauben...
Stimmt genau.
Um die Arbeit an der Doku zu minimieren, {zweckent|ver}wenden wir die Kommentare im Quelltext (im interface-Teil) zur Erstellung der Systemdokumentation.
Das hat sich als praktikabel erwiesen.
Das ist Geschmackssache.
Zitat:
Was ein Beispiel für eher weniger gute Doku ist. Was man von einer *wirklich* guten Doku erwarten würde:
- Dass sie auch Leute verstehen, die nicht wissen, dass "Absolutwert" ein Synonym für die Betragsfunktion ist
- Dass sie keine Infos wiederholen, die in der Signatur stehen ("X ist ein Ausdruck des Typs Integer oder Real.")
- Dass Randfälle erklärt werden. Was passiert, wenn man NaN übergibt?
Exception oder auch NaN? Das wären Infos, die einen Mehrwert bieten.
Melde es bei Embacadero
Ich scheine bei der Wahl meiner Beispiele kein glückliches Händchen zu haben.
Zitat von
Furtbichler:
Übrigens, falls es dich interessiert: Ein Methodenname darf gerade nicht den Algorithmus ('Rekursiv') wiederspiegeln, sondern kurz und knapp erklären, was die Methode anstellt.
Hier ist "Recursively" Teil der Funktionsbeschreibung. Es werden auch Kindeskinder betrachtet. Das ist keine Aussage über den Algo, der dahinter steckt. Auch der kann rekursiv sein (und es es hier vermutlich auch). Aber er muss es nicht. Fakt ist, dass "rekursiv" nicht nur einen Algo beschreibt, sondern auch eine funktionale Anforderung sein kann.
Genau so war es auch gemeint, in der Mengenlehre wird der Begriff Rekursiv auch verwendet.
Wobei das auch ungenau formuliert ist, da es ja nur bedeutet, dass die Menge berechenbar ist. (wenn ich mich recht erinnere)
Aber ich hoffe man versteht es trotzdem.