Es traut sich einfach niemand so alte und häufig benutze Funktionen "anzufassen".
Das macht APIs so schwer: Wenn man sie rausgibt, bedeutet das gleichzeitig, dass man sie partiell in Zement giest. Eine
API nachträglich zu ändern ist nicht mehr so einfach möglich. Aber es gibt Möglichkeiten: Schreib ne schöne, neue Methode und mach die alte deprecated. Und in 10 Jahren kannst du vielleicht drangehen, die alte zu entfernen. Das ist langwierig, ja. Aber, wenn du das jetzt nicht tust, kannst du dir sicher sein, dass du die Methode selbst in 10 Jahren auch nicht los sein wirst.
Zitat:
Aus diesem Grund wurde sie vor ein paar Jahren wenigstens dokumentiert
Schonmal besser als nichts, ja. Aber das ist natürlich keine Heilung. Nur ein Pflaster.
Zitat:
Ich glaube es gibt sogar eine Funktion
DisableRecursive(Form.Control);
, welche die alte aufruft
Guggemalda. Dann fehlt jetzt nur noch das deprecated.
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?
Zitat:
Ich bin auch Fan von Änderungshistorien.
z.B: In der Funktion hat sich ab 01.01.2013 folgendes Verhalten geändert: ...
Oder auch der Autor und das Erstellungsdatum einer Funktion.
Diese Informationen bekommt man zwar auch z.B. über ein Blame in git, aber solche Dinge gehören für mich einfach in eine Dokumentation. (Zumindest bei APIs)
- Kommentare sind keine schlechte Versionsverwaltung. Kommentare sind *etwas anderes*. Da die selben Infos rein zu packen, macht keinen Sinn.
- "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.
- Was bei APIs sinnvoll sein kann (aber nicht muss): Dokumentieren, ab welcher Version etwas etwas neu eingeführt worden ist. So kann man beispielsweise nachgucken, ob Code noch mit ner alten Bibliothek laufen würde. Sowas wie "Läuft meine Komponente auch noch unter Delphi 7?"
- Ähnlich: Breaking changes: Läuft mein Code mit der neuen
API-Version noch?
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...
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.
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.