Quellcode dokumentieren. Wieviel?



  • dot schrieb:

    Guter Code ist selbsterklärend und braucht keine Dokumentation :p

    Von sowas wie Doxygen halt ich persönlich extrem wenig. Das einzige, was man damit erreicht, ist, dass der Code völlig unlesbar wird, weil alles mit Kommentaren zugemüllt ist...

    Ja. Gerade Doxygen finde ich auch furchtbar.

    Generell schreibe ich so wenige Kommentare wie möglich, nur so viele, wie absolut nötig. Und wenn ich Captain-Obvious-Kommentare finde, lösche ich die auch gerne mal.



  • erstellt Ihr gar keine Dokumentation von eurem Code? Ist wahrscheinlich auch vom Umfang und der Umgebung abhängig. Leider kenne ich die Situation, wenn das Programm läuft und dann irgendwann von jemanden die Frage nach der Dokumentation auftaucht. 😮



  • erstellt Ihr gar keine Dokumentation von eurem Code?

    Was heißt "keine"? Ich kommentiere, wo es notwendig ist. Der Rest erschließt sich aus dem Code selbst. Wenn das nicht der Fall ist, ist der Code Mist, und dann ist die Zeit besser darin investiert, ihn zu verbessern, als einen Roman daneben zu schreiben, der nach ein paar Änderungen nicht mehr auf aktuellem Stand ist und mehr Verwirrung als Nutzen stiftet.
    Bei Schnittstellen, die dafür gedacht sind, dass andere sie verwenden, schreibe ich natürlich etwas mehr als im Implementationscode, aber mehr als eine Zeile pro Funktion ist es selten. Und wenn ohnehin völlig offensichtlich ist, was die Funktion tut, ist schon diese eine Zeile überflüssig.



  • dot schrieb:

    Guter Code ist selbsterklärend und braucht keine Dokumentation :p

    DOCH - WO IMMER NOTWENDIG - KNAPP UND PRÄZISE! 😋



  • SBond schrieb:

    dann ist das Verhältnis zwischen Code und Dokumentation nicht selten um die 10:1.

    Das ist schon extrem viel, so viele Kommentare wirst du bei mir nie finden 😉 100:1 oder noch deutlich weniger.

    Es kommt auch stark drauf an, was man schreibt. Schnittstellen werden schon dokumentiert. Aber auch nur "richtige" Schnittstellen, etwas, was als Komponente gedacht ist, und nicht jeder Header. Dann wirds vielleicht auch extern dokumentiert, nicht nur in Form von Kommentaren.
    Im Code selber schreibe ich wenige Kommentare. Ich schreibe aber auch keinen wahnsinnig komplexen Code, keine Physiksimulationen oder so.

    Ich halte den Nutzen von Kommentaren auch für recht fragwürdig. Wenn man sich nicht auskennt, helfen die auch nur sehr bedingt weiter. Als ich neu in der Firma war, habe ich auch sehr viel von unserem Code und vor allem die ganzen Zusammenhänge nicht gekannt und nicht verstanden. Hat etwa ein Jahr gedauert, bis ich dann drin war. Das ganze ist aber auch komplex, umfangreich, aber auch historisch gewachsen und an vielen Stellen ziemlich unsauber, weil das am Anfang anders gedacht war. Wenn man das dokumentieren will, dann braucht man eine richtige, externe Doku, die Konzepte und Zusammenhänge beschreibt, und nicht irgendwelche Kommentare.



  • Mr X schrieb:

    Ich kommentiere, wo es notwendig ist. Der Rest erschließt sich aus dem Code selbst.

    Das heißt bei Libs guckst du auch lieber in den Code als in die Doku?



  • Tyrdal schrieb:

    Mr X schrieb:

    Ich kommentiere, wo es notwendig ist. Der Rest erschließt sich aus dem Code selbst.

    Das heißt bei Libs guckst du auch lieber in den Code als in die Doku?

    Bei Libs sollte das Interface dokumentiert sein.



  • Tyrdal schrieb:

    Mr X schrieb:

    Ich kommentiere, wo es notwendig ist. Der Rest erschließt sich aus dem Code selbst.

    Das heißt bei Libs guckst du auch lieber in den Code als in die Doku?

    Um welche Doku geht es denn? Um Sourcecode? Oder um Schnittstellen/API? Das ist ja schon ein Unterschied.

    Sourcecode (also die Implementierung!) sollte selbsterklärend bzw. selbstsprechend sein. Deshalb benutzen wir ja Hochsprachen, damit wir den Code wie ein Buch/Skript lesen können. Hier geht es um die Entwickler/Mitarbeiter am Code.
    Vermeidliche Optimierungen im Code sind wiederrum selten selbsterklärend. Da sollte dann ein Kommentar mit rein, z.B. was und warum es so gemacht wurde.

    APIs (Schnittstellen, Libs) sollten aber für den Benutzer natürlich dokumentiert sein. Das ist dann schon eine Dienstleistung. Egal wie einfach die API ist, gehört das meiner Meinung einfach mit dazu.



  • Ich bin ein anderes Extrem. Ich dokumentiere fast alle Funktionen, Klassen und schreibe auch mal gerne eine Übersicht des Projekts. Innerhalb des Codes dokumentiere ich nur dann wenn es kompliziert wird.

    Guter Code ist selbsterklärend und braucht keine Dokumentation :p

    Wann ist Code gut? Und wann ist dieser selbsterklärend?

    Meiner Erfahrung nach kann ich den perfektesten und selbsterklärensten Code schreiben. Aber sobald ich diesen anderen Kollegen vorlege, heißt es generell "Verstehe ich nicht!". Vielleicht liegt es daran dass ich generell etwas komplizierter denke, aber ich glaube das Problem ist tiefgründiger. Was für mich selbsterklärend ist, muss es für einen anderen Kollegen nicht unbedingt sein. Und gerade wenn sich ein Kollege in mein Projekt einarbeiten möchte, er die Projekt-spezifischen Fachtermini nicht kennt.

    Mir fällt es aber gerade unter Zeitdruck schwer, gute Namen für Funktionen, Variablen und Klassen zu finden.

    Ich habe schon erlebt dass physikalische Größen nicht dokumentiert waren und ich deswegen tagelang grübeln musste welche Einheit die Größe hatte und auf welchen Takt sich das ganze bezog.



  • Bitte ein Bit schrieb:

    Wann ist Code gut? Und wann ist dieser selbsterklärend?

    Wenn man selber der Autor ist. Anderen denken nicht unbedingt in den gleichen Bahnen wie man selber.



  • Bitte ein Bit schrieb:

    Meiner Erfahrung nach kann ich den perfektesten und selbsterklärensten Code schreiben. Aber sobald ich diesen anderen Kollegen vorlege, heißt es generell "Verstehe ich nicht!".

    Das passiert sogar bei Knuths literate programming. Also man schreibt nur den Kommentar und flicht erläuternd ein wenig Code ein.

    Bitte ein Bit schrieb:

    Vielleicht liegt es daran dass ich generell etwas komplizierter denke, aber ich glaube das Problem ist tiefgründiger. Was für mich selbsterklärend ist, muss es für einen anderen Kollegen nicht unbedingt sein. Und gerade wenn sich ein Kollege in mein Projekt einarbeiten möchte, er die Projekt-spezifischen Fachtermini nicht kennt.

    Die projektspezifischen Fachtermini muss er kennen. Oder im Intranet-Wiki nachlesen.

    Bitte ein Bit schrieb:

    Mir fällt es aber gerade unter Zeitdruck schwer, gute Namen für Funktionen, Variablen und Klassen zu finden.

    Ich habe schon erlebt dass physikalische Größen nicht dokumentiert waren und ich deswegen tagelang grübeln musste welche Einheit die Größe hatte und auf welchen Takt sich das ganze bezog.

    Ahhh!
    Also zunächst mal bewegen wir uns bei den Problemen auf der selben Bahn.
    Ich löse es per

    class Hund{
       double masseInKg;
    

    Du löst es per

    class Hund{
       double gewicht;//masse in kg
    

    Wir beide kotzen bei

    class Hund{
       double gewicht;
    

    Wir haben im Unternehmen

    //global gemacht, um Performance zu sparen
    

    , was neben dem sprachlichen Lacher auch ein inhaltlicher Lacher ist.
    Neulich hab ich fremden Code nicht nachvollziehen können, und siehe da, direkt vor dem Block stand sogar, was ich zum Verständnis gebraucht hätte. Aber vor lauter Blödsinnskommentaren habe ich mir abgewöhnt, sie überhaupt zu lesen, ist mir da aufgefallen. In >99% der Fälle sind die Kommentare nicht hilfreich, vielleicht sogar so veraltet, daß sie lügen.

    Wird aber jetzt gerade behoben, ein paar Progger doxygenisieren ihren Code durch. Leider mit für mich negativem Erfolg, weil bei den Funktionen nicht steht, was und wie sie es machen, sondern nur der Prototyp von C++ nach englisch übersetzt wird.


  • Mod

    volkard schrieb:

    Wir haben im Unternehmen

    //global gemacht, um Performance zu sparen
    

    , was neben dem sprachlichen Lacher auch ein inhaltlicher Lacher ist.

    Der Kommentar passt doch 100% 😃 . Ich würde fast von absichtlicher Rebellion gegen einen dummen Vorgesetzten ausgehen, der meinte, man müsse das global machen, wegen der Performance.



  • class Hund{
      KG gewicht;
    };
    

    wäre noch verständlicher. Meines Wissens kann man das mit C++11 sehr einfach realisieren?


  • Mod

    Artchi schrieb:

    class Hund{
      KG gewicht;
    };
    

    wäre noch verständlicher. Meines Wissens kann man das mit C++11 sehr einfach realisieren?

    Dann aber besser gleich den ganzen Weg gehen und

    class Hund{
      Gewicht gewicht;
    };
    

    in der gleichen Art und Weise, wie beispielsweise Zeit in der Standardbibliothek gehandhabt wird.



  • Da wär ich mir nicht so sicher, ob KG verständlicher ist 😉 Wir haben auch lauter solcher Klassen im Code, wo kein Mensch weiß, was sie bedeuten. Weil irgendjemand das vor 20 Jahren geschrieben hat, und da hat er sich an irgendwelchen DIN und VDA Normen orientiert und da war selbstverständlich klar, was die ganzen 3-4 Buchstaben Abkürzungen bedeuten. Nur hat sich das ganze jetzt massiv weiterentwickelt und keinen interessieren diese Normen von damals.



  • KG war ja nur ein Beispiel, machst du halt ein KGramm draus oder KiloGramm.

    Aber Gewicht geht natürlich auch.

    Auf jeden Fall alles besser als double gewichtInKG.



  • 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;
    


  • Artchi schrieb:

    KG war ja nur ein Beispiel, machst du halt ein KGramm draus oder KiloGramm.
    Aber Gewicht geht natürlich auch.
    Auf jeden Fall alles besser als double gewichtInKG.

    Ist das jetzt ne zweite UN-Welle? Ihr werdet aufs Näschen fliegen damit.



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



  • 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


Anmelden zum Antworten