Kommentare - wie, was, wo, wann

computertrolls schrieb:

Deswegen hat man den Code an dieser Spaltenlänge orientiert.
Heute können gute Editoren eine Linie an dieser Spaltenlänge anzeigen, so das
man sich beim Schreiben daran orientieren kann.
Natürlich kann man heute wesentlich längere Zeilen verwenden, bei Java macht
das sogar Sinn, weil in eine Spaltenlänge von 80 Zeichen da eh fast nichts reinpasst, aber wenn du dir selbst so eine Spaltenbreite definierst, sagen wir mal 132 Zeichen, dann kannst du dich an dieser orientieren.

Passt das Kommentar noch bei deiner definierte Spaltenbreite am Ende einer Zeile hin, dann kommentiere am Ende der Zeile, wenn nicht, dann setze das Kommentar in eine neue Zeile.

Ach noch etwas, für Funktionen und Blockweises kommentieren (denk an die Absätze) sollte man natürlich das Kommentar in eine neue Zeile vor den jeweiligen Block setzen.

Also bspw:

Falsch:

for (int i; i < n; i++){ // Kommentar
  ...
}

Richtig:

/* Kommentar */
for (int i; i < n; i++){ 
  ...
}

hustbaer

@computertrolls
Ist dir fad?

hustbaer schrieb:

@computertrolls
Ist dir fad?

Ich bin erkältet und habe generell ein Helfersyndrom.

hustbaer

Und ein "ich habe die einzige Wahrheit, wer anderer Meinung als ich ist hat einfach Unrecht" Syndrom.

Viel was du hier zum Thema Kommentieren schreibst klingt nämlich theoretisch gut, ist praktisch aber Unfug. Bzw. einfach unpraktikabel weil vom Kosten/Nutzen Faktor her nicht vertretbar.

Wie gesagt, die Variablennamen sind üblicherweise nicht das Problem. Etwas komplexer als std::cout << sth; sind meine Programme leider doch.
Aber gerade das mit den Blöcken halte ich für eine gute Idee.
Hustbär, wie machst du es denn üblicherweise und was würdest du anders machen?

Jockelx

@computertrolls:
Mal aus reinem Interesse:

Du schreibst ja nicht schlecht oder so, aber das Kommentar hört sich so unfassbar falsch an (ist es ja auch), weshalb mich interessiert aus welcher Region du kommst.
Ist das Österreich?

also ich habe in meinem momentanem projekt drei große funktionen (1000 - 2000 zeilen), die ich nicht aufteilen möchte und da mache ich dann sowas:

void funk()
{
     //mach was 1
     {
          struk->data11 = 1;
          struk->data12 = 2;
     }

     //mach was 2
     {
          struk->data21 = 3;
          struk->data22 = 4;
     }
}

der inhalt der blöcke ist an und für sich selbst erklärend, aber bei visual studio kann ich die blöcke "einklappen", sodass dann nur noch die kommentare da stehen und ich dann sehen kann, wo was gemacht wird.

ich finde, dass das sehr gut hilft.

Das Einklappen kann eigentlich jede gute IDE, sogar manche einfache Editoren wie Kate.
Nachteil von solchen Blöcken ist allerdings eben, dass die Gültigkeitsbereiche noch einmal neu getrennt werden. Bei solchen großen Funktionen würde ich aber auch für jede Funktion eine eigene Datei verwenden.
Die Blöcke halte ich leider tatsächlich (zumindest für mich) nicht für die optimale Lösung.

hustbaer

Wade1234 schrieb:

also ich habe in meinem momentanem projekt drei große funktionen (1000 - 2000 zeilen), die ich nicht aufteilen möchte

Was vermutlich ein Fehler ist.
Bei uns fangen die Jungs schon zum Sudern an wenn man Files in der Grössenordnung hat. Was ich persönlich jetzt wieder übertrieben finde, 2000 Zeilen sind IMO net Schlimm für ein File. Aber für eine Funktion ... eieiei.

Kennst du das Method-Object Pattern?

hustbaer

bla-comm schrieb:

Aber gerade das mit den Blöcken halte ich für eine gute Idee.
Hustbär, wie machst du es denn üblicherweise und was würdest du anders machen?

Ich kommentiere keine offensichtlichen Dinge, wie

computertrolls schrieb:

Anders kann es z.B. bei so etwas aussehen:
std::cout << datapoint << endl; // Ausgabe des Messwerts
Wenn man jetzt nach nem Jahr wieder in den Code schaut, dann wäre ohne Kommentar
nicht klar, was da ausgegeben wird, man müsste schließlich erst einmal wissen, was die Variable datapoint darstellt.

Ja, man müsste wissen was dir Variable datapoint darstellt. Wenn man es nicht weiss hat man aber ein anderes Problem als zu wissen was diese Zeile macht, man wird den ganzen Code der mit datapoint arbeitet nicht verstehen. Also entweder (schlechte Lösung) bei der Definition von datapoint dazuschreiben was drin steht (und nur dort), oder (bessere Lösung) nen ausreichend sprechenden Namen verwenden. Wobei ich datapoint jetzt nicht schlecht finde. Ich meine "datapoint" mit "Messwert" kommentieren... dafuq? Kann da etwa jemand kein Englisch?

Weiters halte ich

Jede Funktion sollte kommentiert werden.
Wichtig ist, was sie tut, was die Parameter bedeuten, welche Vorbedingungen die Funktion erfordert und was die Funktion zurückliefert.
Ebenso gehört dazu, welche Expcetion sie wirft und warum, sowie welche Seiteneffekte auftreten können.

für total übertrieben. Funktionen deren "funktion" sozusagen "offensichtlich" ist, genau so wie die Bedeutung der einzelnen Parameter müssen nicht unbedingt dokumentiert werden.
Zu viel zu dokumentieren erzeugt auch oft das Problem dass die Dokumentation anfängt zu lügen wenn Änderungen gemacht werden - weil dann oft vergessen wird die Doku anzupassen. Oder auch ein Klassiker; Änderungen in Funktion X verursachen Änderungen in Funktion Y, weil X von Y aufgerufen wird. z.B. welche Exceptions aus X rausfliegen können.

(Bzw. manchmal lügt die Doku sogar schon am dem 1. Moment. Ich sehe das relativ oft dass Leute ne Doku wo dazuschreiben, bei etwas was sie gerade erst programmiert haben, und die Doku dann einfach was anderes sagt als was die Implementierung macht. Die Unterschiede sind meist im Detail, aber herrjeh, wenn man sich nicht drauf verlassen kann dass es exakt stimmt, dann tut's vermutlich auch die grobe Vorstellung die man durch Funktionsname + Parameternamen bekommt. Zumindest weiss man dann was man nicht weiss und ggf. in der Implementierung nachgucken müsste.)

Weiters ist jede Zeile Doku die man anpassen oder sogar neu schreiben muss ein weiterer Refactoring-Hemmer. Und Refactoring will man nicht noch mehr ausbremsen als es das automatisch durch das Thema "kein kundensichtbarer Vorteil" schon wird.

Also lieber gucken dass man seine Bezeichner so wählt dass man mit wenig bis keiner Doku auskommt.

Was dagegen wichtig ist, ist ne Doku die das grosse Ganze erklärt. Also die grossen Komponenten, wofür sie gut sind und wie sie zusammenspielen. Ein \brief zu jeder Klasse + von Doxygen daraus generierte Übersicht ist oft viel viel mehr Wert als wenn jede Funktion jeder einzelnen Klasse dokumentiert ist, aber keine Kurzbeschreibung was die Klasse überhaupt soll.

Und nochmal ne Nummer grösser: die wichtigsten Module (Libraries), wo inetwa welche Funktionalität drin ist etc.

----

Macht aber natürlich auch einen Unterschied was man entwickelt. Wenn man langlebige Libraries entwickelt, dann ist es vermutlich wichtiger jede Klasse und jede nicht-triviale Funktion zu dokumentieren. Wenn man ne Anwendung entwickelt, dann ist es eher nicht so wichtig. Und wenn man "lebendigen" Code hat, der sich dauernd ändert und ständig selbst neu erfindet, dann auf jeden Fall bitte nicht jeden Fliegenschiss dokumentieren.

Jockelx schrieb:

@computertrolls:
Mal aus reinem Interesse:

Du schreibst ja nicht schlecht oder so, aber das Kommentar hört sich so unfassbar falsch an (ist es ja auch), weshalb mich interessiert aus welcher Region du kommst.
Ist das Österreich?

Ich komme aus Süddeutschland.

Ich wusste gar nicht, dass ein Kommentar maskulin ist, für mich klingt das auch irgendwie seltsam, wenn man "der Kommentar" sagt. Für mich ist ein Kommentar ein Neutrum, ich denke da nicht an einen Kommentator, also ein Person, sondern an ein geschlechtsloses Subjekt.
Der Duden und die Rechtschreibung definiert das leider, wie ich nun sehen muss, anders.

computertrolls schrieb:

Jockelx schrieb:

@computertrolls:
Mal aus reinem Interesse:

Du schreibst ja nicht schlecht oder so, aber das Kommentar hört sich so unfassbar falsch an (ist es ja auch), weshalb mich interessiert aus welcher Region du kommst.
Ist das Österreich?

Ich komme aus Süddeutschland.

Ich wusste gar nicht, dass ein Kommentar maskulin ist, für mich klingt das auch irgendwie seltsam, wenn man "der Kommentar" sagt. Für mich ist ein Kommentar ein Neutrum, ich denke da nicht an einen Kommentator, also ein Person, sondern an ein geschlechtsloses Subjekt.

Das ist es j auch, was das Deutsche für andere so aufwendig zu lernen ist. Das Geschlecht hat im Deutschen nichts mit Logik zu tun.
Du sagst ja auch nicht das Tisch, das Berg, das Brücke etc.

hustbaer schrieb:

Wade1234 schrieb:

also ich habe in meinem momentanem projekt drei große funktionen (1000 - 2000 zeilen), die ich nicht aufteilen möchte

Was vermutlich ein Fehler ist.
Bei uns fangen die Jungs schon zum Sudern an wenn man Files in der Grössenordnung hat. Was ich persönlich jetzt wieder übertrieben finde, 2000 Zeilen sind IMO net Schlimm für ein File. Aber für eine Funktion ... eieiei.

Naja diese ganzen Blöcke berechnen z.b. Rechtecke oder Koordinaten für Zeichenketten (benutzeroberfläche mit winapi) und das dann alles eben 60 mal, weil 60 rechtecke und ich sehe keinen Vorteil darin, 60 Funktionen zu erstellen, weil das ja eingeklappt auf den bildschirm passt.

Kennst du das Method-Object Pattern?

Nö, allerdings versuche ich mich momentan auch daran, funktionsorientiert zu programmieren. Zumindest bisher finde ich das gar nicht so schlecht.

Wade1234 schrieb:

Naja diese ganzen Blöcke berechnen z.b. Rechtecke oder Koordinaten für Zeichenketten (benutzeroberfläche mit winapi) und das dann alles eben 60 mal, weil 60 rechtecke und ich sehe keinen Vorteil darin, 60 Funktionen zu erstellen, weil das ja eingeklappt auf den bildschirm passt.

Was spräche gegen eine generische Funktion, die alle 60 Rechtecke abdeckt?

gute frage eigentlich, nichts wahrscheinlich.

hustbaer

Na dann wäre das die noch viel bessere Variante

wenn ich sowas realisieren möchte, bräuchte ich ein array aus entsprechenden datenstrukturen, oder?

Wade1234 schrieb:

wenn ich sowas realisieren möchte, bräuchte ich ein array aus entsprechenden datenstrukturen, oder?

Das wäre eine Lösung, aber auch eine Liste, die auf die Datenstrukturen verweist würde gehen.
Kommt halt darauf an, was du damit machen willst und ob z.B. die Anzahl an Elementen wachsen können soll.
Selbst Bäume würden gehen, wenn auch im gegebenen Fall wahrscheinlich etwas over engineered.