3. Dokumentieren

Dokumentieren

  • ?

    Man soll Code dokumentieren, weil man sich sonst später nicht mehr auskennt.

    Was haltet ihr von der Aussage?

    0
  • _

    Man soll essen, damit man nicht verhungert.

    Was hältst du von der Aussage?

    0
  • ?

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

    0
  • ?

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

    0
  • ?

    Ausnahmen bestätigen die Regel...

    0
  • Mod

    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)

    0
  • ?

    314159265358979__ schrieb:

    Ausnahmen gibts natürlich immer.

    0
  • ?

    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.

    0
  • ?

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

}
    0
  • V

    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.

    0
  • ?

    volkard schrieb:

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

    Redest du jetzt vielleicht über Spezifikation?

    0
  • V

    Steffo schrieb:

    volkard schrieb:

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

    Redest du jetzt vielleicht über Spezifikation?

    Nein.

    0
  • M

    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.

    0
  • ?

    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.

    0
  • Mod

    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.

    0
  • M

    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.

    0
  • V

    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.

    0
  • ?

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

    0
  • V

    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.

    0
  • ?

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

    0
Anmelden zum Antworten