Dokumentieren

Im Grunde richtig. Im Extreem-Programming sind Kommentare jedoch verpönt. Dort ist die Maxime sprechende Variablen- und Funktionsnamen zu wählen, so dass Kommentare unnötig werden. Allerdings gibt es für jede Regel eine Ausnahme...

Steffo schrieb:

Im Extreem-Programming sind Kommentare jedoch verpönt. Dort ist die Maxime sprechende Variablen- und Funktionsnamen zu wählen, so dass Kommentare unnötig werden.

Ist im Grund genommen ja auch richtig. Ausnahmen gibts natürlich immer. Aber ansonsten sind Komentare nicht nötig...

Ausnahmen bestätigen die Regel...

SeppJ

314159265358979__ schrieb:

Ist im Grund genommen ja auch richtig. Ausnahmen gibts natürlich immer. Aber ansonsten sind Komentare nicht nötig...

Doch. Natürlich schreibst du nicht

int maximum; // Maximum value

oder

PhoneNumber get_phone_number(); // Returns phone number

Aber an nicht-trivial Algorithmen schreibt man schon dran, was das sein soll:

// The  MT19937 equidistributed uniform PRNG as described in Matsumoto, Nishimura 
// "Mersenne twister: a 623-dimensionally equidistributed uniform pseudo-random 
// number generator", ACM Transactions on Modeling and Computer Simulation 8 (1): 
// 3–30. doi:10.1145/272991.272995
class MersenneTwister { ... };

oder bei Sachen auf die man nicht auf den ersten Blick kommt:

int result = 2 * XYZ + ABC;  // Need a factor 2 because of REASON.

(Mir fiel bei letzterem kein simples Beispiel ein, aber jeder hat schon einmal erlebt, das man mal Konstrukte hat, die auf den ersten Blick falsch aussehen, wenn man nicht den vorhergehenden Programmverlauf ganz genau studiert hat)

314159265358979__ schrieb:

Ausnahmen gibts natürlich immer.

Die Frage war doch dokumentieren und nicht kommentieren.

Dokumentieren muss sein, sonst weiß ja keiner wozu die Software da ist und wie man sie benutzt.

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)
{

}

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.

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.

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.

@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.

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.

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