Dokumentieren
-
OK, die Erfahrungen anderer Mitglieder zählen nicht? Deine ist die richtige?
-
Steffo schrieb:
OK, die Erfahrungen anderer Mitglieder zählen nicht? Deine ist die richtige?
Es gibt viele Leser hier, die meinem Wort einen gewissen erhöhten Wert beimessen. Vielleicht, weil ich relativ oft treffe und kein Blatt vor den Mund nehme.
Aber ich treffe natürlich nicht immer. Meine Haupt-Aussage ist "Alle Generalisierungen sind falsch." Und die nächste ist "Glaub in Foren nur den Leuten, die ihre Thesen gut begründen." Na, in dieser Hinsicht bin ich in diesem Thread ganz hinten. Das macht aber nix, da die Begründungen hier auch alle religiös sind.
-
Ein bisschen mehr Demut würde nicht schaden.
Du scheinst viele Erfahrungen gesammelt zu haben und in Diskussionen ziemlich oft recht behalten, wenn du denn mal begründest, aber um so etwas geht es letztendlich nicht, zumindest sollte es das nicht, genauso wenig um das Ansehen.Eigentlich trete ich nur ungern Menschen zu nahe, aber ich habe auch die Eigenschaft, kein Blatt vor dem Munde zu nehmen, deswegen folgende Worte von mir:
Deine Erfahrungen sind sicherlich sehr wertvoll für jedes Unternehmen und du magst auch ziemlich oft "treffen", aber es scheint deinem Charakter inhärent zu sein, dass das du nun weniger selbstkritisch über dein Verhalten nachdenkst. Wohin das führen kann, überlasse ich deinen Gedanken. Ich will dir ja schließlich auch irgendwo nicht zu nahe treten...L. G.
Steffo
-
Meine Erfahrung ist, das sobald etwas wirklich Dokumentation nötig hat, die Header-Dokumentation vollkommen versagt. Wir benutzen zwar Doxygen und generieren damit eine Dokumentation, aber das was in den Header selbst steht ist zum Teil völlig unbrauchbarer Latex-Code. Und die Doxygen documentation ersetzt dann auch kein Tutorial sodnern gibt nur schnell Quelle+Formeln+Anwendungszweck an.
Zu der Sache mit den sprechenden Funktionsnamen: Wenn es ordentliche Programmierrichtlinien gibt, dann stellen sich viele Fragen nicht. Die Frage, wer sich zum Beispiel um das Speichermanagement kümmert gehört einfach festgelegt. Entweder indem smart-ptr verwendet werden(=Speicher räumt sich selbst auf) oder indem zentral festgelegt wird, dass der der anfordert auch freigibt(oder andere Konventionen). Ähnliches gilt für exceptions und anderes. Wenn solche Regeln existieren und eingehalten werden reicht wirklich in 90% der Fälle der Funktionsname aus.
-
SeppJ schrieb:
ich... schrieb:
pox schrieb:
Man soll Code dokumentieren, weil man sich sonst später nicht mehr auskennt.
Was haltet ihr von der Aussage?
würde sagen, dass stammt aus der zeit, als man noch mit assembler programmiert hat. Heute sollte man code so leserlich und sprechend schreiben, dass man sich auch noch später auskennt.
Ich behaupte mal, dass dies nicht allgemein möglich ist. Außer man nimmt mit hundertzeichigen Bezeichnern vorlieb. Manche Algorithmen sind einfach an sich schwer zu verstehen.
hab ja auch nicht gesagt, dass das immer geht, aber man sollte es so machen. Man sollte den leuten nicht beibringen, dass sie ihren code dokumentieren sollen, damit sie sich später auskennen, sondern ihren code gleich so schreiben sollen, dass man sich schnell auskennt. Nur wenn das wirklich nicht geht, sollte man dokumentieren. In den meisten fällen ist die doku, irgendwann älter als der code.
-
otze schrieb:
Zu der Sache mit den sprechenden Funktionsnamen: Wenn es ordentliche Programmierrichtlinien gibt, dann stellen sich viele Fragen nicht. Die Frage, wer sich zum Beispiel um das Speichermanagement kümmert gehört einfach festgelegt. Entweder indem smart-ptr verwendet werden(=Speicher räumt sich selbst auf) oder indem zentral festgelegt wird, dass der der anfordert auch freigibt(oder andere Konventionen). Ähnliches gilt für exceptions und anderes. Wenn solche Regeln existieren und eingehalten werden reicht wirklich in 90% der Fälle der Funktionsname aus.
Ja, dem kann ich zustimmen. Was für mich aber noch ein bisschen untergeht, ist der Punkt, ob man überhaupt immer den Code lesen will. Angenommen, ein Kollege hat ein Framework geschrieben. Besteht aus hunderten Klassen und abertausenden Zeilen Code, hat sprechende Funktionsnamen usw... Und jetzt will/muss man das auch für was anderes verwenden. Das wär eine kurze Doku, die erklärt, wie man das Framework benutzt und was zu beachten ist, viel produktiver, als sich durch hunderte Klassen durchzuwühlen und sich zusammenzureimen, was da warum passiert.
-
Mechanics schrieb:
Was für mich aber noch ein bisschen untergeht, ist der Punkt, ob man überhaupt immer den Code lesen will. Angenommen, ein Kollege hat ein Framework geschrieben. Besteht aus hunderten Klassen und abertausenden Zeilen Code, hat sprechende Funktionsnamen usw... Und jetzt will/muss man das auch für was anderes verwenden. Das wär eine kurze Doku, die erklärt, wie man das Framework benutzt und was zu beachten ist, viel produktiver, als sich durch hunderte Klassen durchzuwühlen und sich zusammenzureimen, was da warum passiert.
Sind nicht die Codebeispiele das beste an der Doku?
-
hehehe schrieb:
Mechanics schrieb:
Was für mich aber noch ein bisschen untergeht, ist der Punkt, ob man überhaupt immer den Code lesen will. Angenommen, ein Kollege hat ein Framework geschrieben. Besteht aus hunderten Klassen und abertausenden Zeilen Code, hat sprechende Funktionsnamen usw... Und jetzt will/muss man das auch für was anderes verwenden. Das wär eine kurze Doku, die erklärt, wie man das Framework benutzt und was zu beachten ist, viel produktiver, als sich durch hunderte Klassen durchzuwühlen und sich zusammenzureimen, was da warum passiert.
Sind nicht die Codebeispiele das beste an der Doku?
Mag sein. Aber ein gutes Codebeispiel ist auch eine Art Doku. Wenn es jemand einfach auf den Punkt bringt und gleich klar ist, was zu tun ist, reicht auch ein Beispiel. Hauptsache, man muss sich das Beispiel nicht selber aus einer wesentlich größeren Menge Code zusammensuchen.
-
Schönes und sehr altes Thema der Programmierung!
Kommentare und gesonderte Dokumentationen machen Mühe, genauso wie ein ordentliches Design. Brauche ich nicht? Na gut, wenn das Programm nicht gewartet oder erweitert werden muss. Proggen ist nun einmal etwas mehr als das Aneinanderreihen von Codezeilen!!! :p
-
Trivialbeispiele anzufuehren ist keine Argumentation. Es kann vieles im Typ kodiert werden, aber eine komplexe Typhierarchie wirft eigene Probleme auf. Dann gibts da noch die C-Fraktion, wo gern mit Zeigern gearbeitet wird. Da wuensche ich mir, dass die Besitzverhaeltnisse als Kommentar/Dokumentation im Header angegeben sind.
-
Dass man sprechende Namen verwendet, ist selbstverständlich. Aber dass dies genügt, ist Unsinn. Selbst der tollste und aufgeräumteste Code braucht Dokumentation. Weil es was andres ist, ob man Code liest oder Prosa. In der Regel versteht man letzteres schneller und besser.
Leute, die behaupten, auf Dokumentation des Codes verzichten zu können, wissen entweder nicht, wovon sie reden, oder sie sind schlicht zu faul, anständig zu arbeiten. Ich halte das jedenfalls nicht für eine professionelle Attitüde.
Dass die Dokumentation früher oder später veraltet ist? S. oben: Nicht wenn gute Entwickler im Projekt sind.
Im Übrigen ist es auch für den Code sehr nützlich, dokumentieren zu müssen. Wenn ich weiß, dass ich werde aufschreiben müssen, wozu eine Klasse eigentlich gut ist, was eine Funktion eigentlich macht oder welche Pre- und Post-Conditions sie hat (usw.), denke ich sorgfältiger über den Code nach, den ich schreiben möchte.
-
Klares jein zu allem
Gut geschriebener Code kommt mit wenig Doku aus. Klar gibt es das grobe Design, das man noch irgendwo gesondert dokumentieren sollte. Was eine Funktion macht, sollte aus der Definition ersichtlich sein. Wozu eine Klasse dient, sollte aus ihrem Namen und ihrer Verwendung ersichtlich sein.Bei komplizierten Algorithmen ist es klar, dass man dazu schreibt, was Sache ist, genauso bei Dingen, die man selber nicht erwarten würde - z.B. der von SeppJ genannte Faktor 2.
Orlando schrieb:
Weil es was andres ist, ob man Code liest oder Prosa.
Je sauberer der Code geschrieben wurde desto besser kann man ihn einfach runterlesen wie Prosa. Das gilt zumindest für ca. 90% des Codes, Ausnahmen siehe oben.
In der Regel versteht man letzteres schneller und besser.
Ich kenne meinen eigenen Code-Schreibstil besser als anderer Leute Prosa-Stil. Im Code lese ich mich schneller wieder ein als in ein Buch.
Im Übrigen ist es auch für den Code sehr nützlich, dokumentieren zu müssen. Wenn ich weiß, dass ich werde aufschreiben müssen, wozu eine Klasse eigentlich gut ist, was eine Funktion eigentlich macht oder welche Pre- und Post-Conditions sie hat (usw.), denke ich sorgfältiger über den Code nach, den ich schreiben möchte.
Das erreiche ich viel besser während ich die Tests für den Code schreibe, weil ich mit Tests in Code ausdrücke, was der eigentliche Code kann. Damit entfällt auch das Problem des Veraltens - wenn der Code geändert wird, müssen die Tests geändert werden, damit sie weiterhin durchlaufen. Dieser Zwang ist besser als jede hätte-gern-Disziplin mit der man die Kommentare zusammen mit dem Code ändert.