3. Quellcode dokumentieren. Wieviel?

Quellcode dokumentieren. Wieviel?

  • A

    goi schrieb:

    Ich dokumentiere das Interface mit Doxygen und im Code je nach dem, wenn es Sinn macht. Ich hasse aber so redundante Sachen wie "Initialisiere x mit Null" oder "Erstelle ein Objekt vom Typ Foo". Der Kracher war neulich sowas hier

    // Iteriere über vec und addiere alle Einträge zu sum
double sum = 0.0;
for(double vi : vec)
  sum += vi;

    Das hatte doch Bjarne Stroustrup in seinem letzten Buch erklärt. Solche unnützen Kommentare rührendaher, weil sie in Lehrbüchern zu finden sind. Also in den Lehrbüchern machen sie natürlich Sinn. Aber viele meinen danach so was mit in die Praxis bzw. reale Welt übernehmen zu müssen, was natürlich falsch ist.

    0
  • M

    Hi Artchi,

    Stroustrup hat das kurz und bündig auf den Punkt gebracht: "Halten sie Kommentare knackig!"

    Der beste Kommentar ist immer noch ein flüssig wie ein Brief zu lesender Quelltext. Vor allem ist der nie veraltet.

    Gruß Mümmel

    0
  • B

    Lange interessante Diskussion, so alt wie die Programmierung. Jeder hat da seinen
    eigenen Stil! Ich kommentiere:

    1. den Zweck der Anwendung
    2. den Zweck von Funktionen
    3. physikalische oder sonstige nicht allgemein verständliche Grössen
    4. Erklärung komplexer Algorithmen
    5. Abbruchbedingungen bei Iterationen
    6. Baustellen während der Entwicklung

    Ich selbst möchte mich in meinem Code zurechtfinden, wenn ich (oder jemand anderes)
    später daran etwas ändern oder erweitern will. Alles im allem komme ich so auf einen Anteil
    der Kommentare von etwa 2% des Codes. Das muss genügen, sollte aber sein!

    0

  • Hallo,

    ich handhabe das auch so, dass das Programm und Funktionen / Methoden mit dem Einsatzzweck kommentiert werden. Das sollte eigentlich (bei anständigen Variablenbezeichnern) vollkommen ausreichen.

    [OT]Geht es nach meinem Chef müsste ich Kommentare:Code auf 4:1 kommen. - Zum Glück sieht mein Abteilungsleiter das nicht so.[/OT]

    0
  • ?

    Vorbedingungen, Nachbedingungen und Invarianten einer Funktion nicht vergessen, sofern sie nicht aus dem Code auf einen Blick hervorgehen.

    Kostet etwas Zeit und klingt nicht so lässig wie "guter Code braucht keinen Kommentar", kann spätere Änderungen am Code aber ungemein erleichtern.

    0
  • S

    Was mir bisher etwas fehlt ist der Grund.

    Ich kommentiere gerne mal, warum ich etwas mache. Was ist der Grund warum ich mir selbst eine Wurzelfunktion schreibe anstatt std::sqrt zu nutzen. Und sowas alles

    0
  • R

    Gutes Schnittstellen-Design und gute Schnittstellen-Doku macht Doku auf Code Ebene fast unnötig.

    Hab in der Parxis schon viele Ansätze erlebt ...

    undokumentiert ist Sch ....
    aber erzwungene Systematische Doku ist es auch ^^

    Ciao ...

    0
Anmelden zum Antworten