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?
Weil erstens eine System/
API-Doku vollständig sein sollte und zweitens eine Doku erweitert werden sollte. Keine Doku wird selten erweitert. Eine
API, die aus elementaren Operationen besteht, die aussagekräftige Namen haben ist selbsterklärend. Das ist die Krux bei guten
API: Einerseits gehört die Doku dazu, weil dort eben auch steht, was für Seiteneffekte es gibt, Beispiele, Exceptions, der ganze Kram eben, Und da sieht es eben blöd aus, wenn in der Doku steht: "CreateForm: Guess what the function does..." oder "The name says it all" (obwohl, warum eigentlich nicht).
Ein gutes Tool macht dir Doku aus reinem Code ohne Kommentaren. Du schreibst also nur die Kommentare, die eien Mehrwert bieten und den Rest macht das Tool. Dadurch wird die Doku vollständig. Es mag merkwürdig aussehen, dass da "etwas fehlt". Ich fühle auch so. Aber, wenn alles, was mir einfällt, eine Paraphrase ist, die ich schreiben und andere Lesen müssen, lass ich sie lieber doch gleich weg. Doku muss kein Kunstwerk sein. Sie muss den Stakeholdern helfen.
Zitat:
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.
Klar.
Zitat:
z.B. von Prüfern der externen Revision
Und die erwarten, dass Bezeichnernamen paraphrasiert werden? Wenn ja, sollte man die mal nach dem Warum fragen.
Zitat:
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.)
Und das kann, je nach Stakeholder, ja ein Mehrwert sein. Da hast du vollkommen recht. Nur Paraphrasen haben eben keinen Mehrwert. Und das war meine Aussage.
Zitat:
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.
Und das ist auch gar nicht zu beanstanden. Je näher die Doku am Code ist, desto größer ist die Wahrscheinlichkeit, dass sie auch gepflegt wird, d.h., aktuell und richtig ist. Das ist so schon schwer genug. Wenn das in nem externen Word-Dokument wäre (auch sowas hab ich schon gesehen), ist das ungleich schwieriger. So weit weg vom Code kannst du nur Zeug dokumentieren, das sich sehr langsam ändert. Also beispielsweise Architekturzeug. Das geht noch einigermaßen. Dann aber versioniert im selben Repository. Wenn du anfängst, einzelne Methoden per Word zu dokumentieren oder vielleicht noch irgendwie auf Papier zu drucken, hast du i.d.R. kaum eine Chance, das aktuell zu halten.