Quellcode dokumentieren. Wieviel?

Bitte ein Bit

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.

Tyrdal

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.

volkard

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.

SeppJ

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.

Artchi

class Hund{
  KG gewicht;
};

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

SeppJ

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.

Mechanics

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.

Artchi

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.

goi

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;

volkard

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.

Artchi

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.

muemmel

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

berniebutt

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!

inflames2k

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]

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.

Skym0sh0

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

RHBaum

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