Dokumentieren

[volkard]

Steffo schrieb:

Die Dokumentation lässt sich ja über Kommentare erreichen.

/**
 * This function does...
 *
 * @param a
 *        Neccessary for...
 * @return
 *        Returns 0 if successfully, 1 else.
 */
public int myFunction(int a)
{

}

Wobei diese zwanghaften Header meist keine nutzbringende "Dokumentation" erzeugen.

[Gast]

volkard schrieb:

Wobei diese zwanghaften Header meist keine nutzbringende "Dokumentation" erzeugen.

Redest du jetzt vielleicht über Spezifikation?

[volkard]

Steffo schrieb:

volkard schrieb:

Wobei diese zwanghaften Header meist keine nutzbringende "Dokumentation" erzeugen.

Redest du jetzt vielleicht über Spezifikation?

Nein.

[Mechanics]

volkard schrieb:

Wobei diese zwanghaften Header meist keine nutzbringende "Dokumentation" erzeugen.

Seh ich eigentlich auch so. Das führt meist dazu, dass irgendwas in der Art dransteht:

//returns the name
string getName() const;

Wichtig sind Konzepte und Zusammenhänge, und die sollte man schon dokumentieren, vielleicht in einem Wiki oder so. Natürlich helfen auch Kommentare oft, wie bei den Beispielen von SeppJ, aber die meisten Kommentare blähen den Code einfach nur unnötig auf, weil viele Leute nur irgendwas triviales kommentieren.

[ich...]

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.

[SeppJ]

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.

[Mechanics]

SeppJ schrieb:

Außer man nimmt mit hundertzeichigen Bezeichnern vorlieb.

Selbst dann nicht. Es gibt einfach zu viele Details, die man wissen muss. Kann die Funktion null zurückgeben, schmeißt sie Exceptions, wer gibt den Speicher frei, muss zuvor noch was initialisiert werden, welche Wertebereiche sind zulässig usw... Sprechende Funktionsnamen reichen nicht.

[volkard]

Mechanics schrieb:

SeppJ schrieb:

Außer man nimmt mit hundertzeichigen Bezeichnern vorlieb.

Selbst dann nicht. Es gibt einfach zu viele Details, die man wissen muss. Kann die Funktion null zurückgeben, schmeißt sie Exceptions, wer gibt den Speicher frei, muss zuvor noch was initialisiert werden, welche Wertebereiche sind zulässig usw... Sprechende Funktionsnamen reichen nicht.

Doch.

[Gast]

@Volkard: Was ist das eigentlich für eine Art zu kommunizieren?
Zu mir sagst du "Nein", zu Mechanics "Doch". --> Aha

[volkard]

Steffo schrieb:

@Volkard: Was ist das eigentlich für eine Art zu kommunizieren?
Zu mir sagst du "Nein", zu Mechanics "Doch". --> Aha

Ich gebe ein wenig die Richtung.
Die Details dürft Ihr selber austüfteln.

[Gast]

OK, die Erfahrungen anderer Mitglieder zählen nicht? Deine ist die richtige?

[volkard]

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.

[Gast]

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

[otze]

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.

[ich...]

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.

[Mechanics]

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.

[hehehe]

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?

[Mechanics]

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.

[berniebutt]

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

[knivil]

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.