Hallo,
Am Sonntag, 12. Dezember 2004 23:59, schrieb Eric Schaefer:
On Sat, 2004-12-11 at 17:13 +0100, Erik Schanze wrote:
Ich suche nach Informationen oder Erfahrungen von Entwicklern, wie man am besten Sourcecode (speziell C++) kommentieren sollte, damit die Kommentare einheitlich und gut verarbeitbar sind. Gibt es (Quasi-)Standards?
<schnipp>
Kommentiere innerhalb der Methoden, WARUM Du etwas tust, nicht WAS Du tust. Wer sich in die Tiefen der Quellen vorwagt, wird das WAS sehen. Das WARUM aber erfordert Wissen um den Kontext, welches beim Betrachter in dem Ausmaß evtl. nicht vorhanden ist. Beispiel:
++i; // inkrementiere den Zähler [Ach nee...]
myWidget->SetCaption(dbConnection->getCurrentValue(3)); // stelle den Kundennamen im Textfeld dar
Im ersten Fall erzeugst Du nur Rauschen, im zweiten Fall ist das Wissen um die Datenbankstruktur erforderlich. Durch den Kommentar erkennt der Nutzer was da passiert, ohne daß er kompliziert ausknobeln muß, was denn Wert 3 in der Datenbank ist.
Folgendes komplett meine humble opinion:
Hm, da hätte ich noch einen Verbesserungsvorschlag: #define CustomerNameId 3 oder enum { CustomerNameId = 3 }; oder static const int CustomerNameId = 3 ; an geeigneter Stelle, damit hat man sowohl ein wenig mehr selbstdokumentierenden Quellcode, z.B. myWidget->SetCaption(dbConnection->getCurrentValue(CustomerNameId)); als auch, wie hoffentlich bekannt, weniger Probleme, sollte sich die 3 mal zur 4 wandeln :) Kommt "dbConnection->getCurrentValue(CustomerNameId)" häufiger vor, vielleicht in eine kleine inline-Funktion "customerName(dbConnection)" auslagern, senkt sowohl Fehleranfälligkeit als auch Code-Lesedauer: myWidget->SetCaption(customerName(dbConnection));
Kernaussage: Vor allem auf selbstdokumentierenden Code achten, spart Dir sowohl Kommentare (den man ja bei jeder Codeänderung immer mit ändern muß, also doppelte Arbeit hat, wird gerne vergessen, und falsche Kommentare sind schlechter als keine), hilft Dir aber auch selbst, den eigentlichen Code zu überblicken und im Griff zu behalten.
Persönlich kapsele ich auch gerne einfache Datentypen in Strukturen oder Klassen (alternativ typedef, #define & Co.), denn ich finde if( Values.includes(Othervalue) ) lesbarer, weniger fehleranfällig und weniger nach Kommentar bittend als if( Value1 <= Othervalue && Value2 >= Othervalue ) Der Sinn lokaler Variablen wird auch schneller deutlich, wenn die Einheiten im Typnamen (mind. per typedef) eingearbeitet sind. Vergleiche FMeter Distance; und float Distance;
Wenn Du die Bedeutung einer Variablen erklären mußt, solltest Du den Namen der Variablen auch noch einmal überdenken.
Wichtige Kommentare sind IMHO vor allem welche zu Randbedingungen, z.B. default-Werte oder garantiertes Verhalten von Funktionen/Codeabschnitten. Aber vermutlich verlasse ich gerade das Thema Deiner Anfrage?
Gruß Friedrich
PS: "TODO" scheint ein anerkanntes Kennwort zu sein, das von vielen IDEs erkannt und deren nachfolgende Texte automatisch in eine Übersichtsliste extrahiert werden, z.B. // TODO: in eigene Funktion auslagern und mit X zusammenfassen