Was gehört alles in eine richtige Dokumentation?

[MaBuSE]

Zitat:

Zitat von r2c2 (Beitrag 1239640)

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:

Zitat von r2c2 (Beitrag 1239640)

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:

Zitat von r2c2 (Beitrag 1239640)

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.

Zitat:

Zitat von r2c2 (Beitrag 1239640)

- "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!"

Zitat:

Zitat von r2c2 (Beitrag 1239640)

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:

Zitat von r2c2 (Beitrag 1239640)

Zitat:

Und ich bin immer noch der Meinung, dass in der Beschreibung einer API auch eindeutige Funktionen dokumentiert werden sollten.
z.B. die Funktion abs()-> http://docwiki.embarcadero.com/Libra.../de/System.Abs

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:

Zitat von r2c2 (Beitrag 1239640)

Zitat:

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.

[r2c2]

Zitat:

Zitat von Furtbichler (Beitrag 1239643)

Zitat:

Zitat von r2c2 (Beitrag 1239640)

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.

[himitsu]

Zitat:

Zitat von MaBuSE (Beitrag 1239644)

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.

Sowas hatte ich mir vor vielen Jahren mal von Emba gewünscht.

So wie man es vom MSDN kennt, also eine Angabe für welche Version das gültig ist.
Denn vorallem für Komponentenentwickler wäre das bestimmt eine schöne Erleichterung.
(eventuell das Alte auch nicht sofort löschen ... nur in der aktuellen Hilfe nicht direkt verlinken)

[Graberius]

Zitat:

Zitat von r2c2

Besser: Schreib deinen Code so, dass klar ist was er tut. Was eine Methode tun soll, sollte ihr Name verraten. Wenn ein Kommentar nötig ist, bedeutet das in 98,57% aller Fälle, dass entweder der Name falsch ist oder die Methode tut zu viel/das falsche und sollte aufgeteilt werden bzw. etwas anderes tun.

Da ich die Kommentar-Debatte ausgelöst habe werde ich sie hoffentlich auch beenden.
Mir ist auch klar das man einfache Methoden nicht Kommentieren muss/sollte um nicht einen Unleserlichen Kommentar zu gestallten.
Aber einfach mal so ne kleine Frage in den Raum...
Wie gut könnt ihr sehr schnell etwas ändern wenn eine Methode geschrieben wurde ohne das irgendwer es für nötig gefunden hat
zu erklären woher z.B. eine GUID (in Intrexx Standard und in Delphi auch verfügbar)stammt?
Kann sein das man die GUID schnell findet aber ich wünsche viel Vergnügen beim Suchen wenn die GUID zerschossen wurde...
Dann hat man das unschöne Vergnügen folgende Dinge zu tun:

• Denn ersteller Suchen
• Denn gesammten SourceCode durchsuchen
• Die gesammte Applikation durchgehen

Bei kleinen Sachen ist das ja nicht unbedingt ein grosser Aufwand aber wenn man eine Komplexe
Applikation vor sich hat würde man sich Wünschen man könnte nur dem Beschrieb vom Kommentar folgen :wall:

Das Mass halten gehört wohl zu denn Schwierigsten Herausforderungen des Lebens...
Von daher ist niemand Perfekt aber ein Code komplett ohne Kommentar zu erstellen ist ein (schwer)Verbrechen

[Furtbichler]

Zitat:

Zitat von r2c2 (Beitrag 1239645)

Ein gutes Tool macht dir Doku aus reinem Code ohne Kommentaren.

Das bezweifle ich, das es ein Tool gibt, das mir eine Routine dokumentiert, ohne das ich Kommentare schreibe. Was so ein Tool macht, ist den Methodennamen und die Parameter + Typen in ein Template zu klatschen und -ja- die von mir geschriebenen Kommentare da irgendwie reinzupflastern. Altbekannt und banal.

Was ich meine, ist die Frage, ob selbsterklärende API-Funktionen eines redundanten Kommentares bedarf. Wir hatten das Thema lustigerweise heute im Team und als ich anmerkte: "Ja 'CreateForm' mit 'Creates a Form' zu dokumentieren, ist heute blödsinnig, aber Kommentare leben und ein existierender Kommentar wird eher erweitert, als ein nicht vorhandener" Die Argumentation stieß auf Zustimmung

[r2c2]

Zitat:

Zitat von Graberius (Beitrag 1239674)

Wie gut könnt ihr sehr schnell etwas ändern wenn eine Methode geschrieben wurde ohne das irgendwer es für nötig gefunden hat
zu erklären woher z.B. eine GUID (in Intrexx Standard und in Delphi auch verfügbar)stammt?
Kann sein das man die GUID schnell findet aber ich wünsche viel Vergnügen beim Suchen wenn die GUID zerschossen wurde...
Dann hat man das unschöne Vergnügen folgende Dinge zu tun:

• Denn ersteller Suchen
• Denn gesammten SourceCode durchsuchen
• Die gesammte Applikation durchgehen

Bei kleinen Sachen ist das ja nicht unbedingt ein grosser Aufwand aber wenn man eine Komplexe
Applikation vor sich hat würde man sich Wünschen man könnte nur dem Beschrieb vom Kommentar folgen :wall:

Versteh nicht, was du meinst.

Zitat:

Von daher ist niemand Perfekt aber ein Code komplett ohne Kommentar zu erstellen ist ein (schwer)Verbrechen

Ich würde es anders sagen: Es sollte das Ziel sein, Code zu schreiben, der keines Kommentars bedarf. Allerdings ist das ein Ziel, das quasi nie vollständig zu erreichen ist.

Zitat:

"Ja 'CreateForm' mit 'Creates a Form' zu dokumentieren, ist heute blödsinnig, aber Kommentare leben und ein existierender Kommentar wird eher erweitert, als ein nicht vorhandener" Die Argumentation stieß auf Zustimmung

Ein falscher Kommentar ist schlechter als ein nicht vorhandener. Zuerst wirst du in die Irre geleitet, produzierst Bugs und verplemperst Zeit. Dann fängst du an, den Kommentaren zu misstrauen und prüfst alles selbst nach. Das aber macht die Kommentare wiederum wertlos, weil alles selbst nachprüfen, kannst du auch ohne Kommentare. Deshalb ist es wichtig, dass Kommentare gepflegt werden.

Je mehr Kommentare da sind, desto mehr Arbeit ist es sie zu pflegen und desto weniger wird es gemacht. Deshalb ist es nicht gut, unnötige Kommentare zu haben. Zudem: Wenn du nur eine Stelle hast, die du nicht selbsterklärend machen konntest, sodass dort ein Kommentar nötig ist, dann wird dieser eine Kommentar herasusstechen. Man merkt gleich: "Oh, das ist eine komplizierte Stelle, da muss ich aufpassen, wenn ich was ändere und ich muss den Kommentar lesen und ggf. anpassen". Wenn du überall Kommentare hast, hast du diesen Effekt nicht.

Kommentare sind wie Antibiotika. Wenn du sie brauchst, sind sie gut und helfen dir. Es ist aber keine gute Idee, präventiv täglich welche zu nehmen, wenn man sie nicht brauchst. Kommentare sind nicht inhärent gut. Sie sind ein manchmal nicht zu umgehendes Übel.