spieleprogrammierer.de - Forum und Wiki zur Spieleprogrammierung und Spieleentwicklung

Wieso soll ich etwas, was sowie so schon klar definiert ist, noch weiter beschreiben? Wenn der Sinn und Nutzen einer Funktion aus Dokumentation und Code ersichtlich ist, und das sollte bei gutem Code so sein, dann erzeugt man mit Code-Kommentaren ausschließlich Overhead. Man kann übrigens jeden Algorithmus in einem bestimmten Maße modular aufbauen und übersichtlich gestalten, wenn der Code also unübersichtlich ist, so liegt es nicht am Algorithmus, sondern am Entwickler.

In einem aktuellen Projekt in der Firma arbeiten wir hauptsächlich mit API-Dokumentation und obwohl der Code sehr systemnah und damit auch entsprechend komplex ist, reicht die Dokumentation vollkommen. Zu viele Kommentare im Code würden das Layout und vor allem den Lesefluss stören. Letztendlich ist mir der Lesefluss beim Verstehen von Code am wichtigsten, da durch einen guten Lesefluss neben dem Verständnis der Funktion auch die verschiedenen Ausführungspfade klar werden.

Mein Fazit: Kommentare maximal zur leichten Strukturierung, nähere Beschreibungen gehören nicht in den Code, da moderne Programmiersprachen ausdrucksstark genug sind. Dokumentation gerne, Kommentare sehe ich jedoch als überflüssig an. Kommentare finden bei mir aktuell nur eine ähnliche Anwendung wie auch bei Dot.

Zitat von »Spiele Programmierer«

Zitat

der Code würde beispielsweise an Ausdrucksstärke gewinnen, wenn die Methode "Process" mittels ihres Rückgabewerts mitteilt, ob der Datensatz weiter vorhanden sein soll

Die Methode könnte zb.:

1. Den Datensatz lösche
   
2. Datensatz so lassen wie er ist.
   
3. Den Datensatz auf mehrere Datensätze aufteilen
   
4. ....

Der Sinn der Methode ist es ja, nach einer irgendwo zuvor definierten Regel die Daten zu verarbeiten.
Und natürlich sollte in der Dokumentation stehen, dass die Daten evt. gelsöcht etc. werden.

das ändert aber nichts daran, dass ein Datensatz sich nciht selbst verarbeiten sollte (was ich auch angemerkt habe)
die Methode, die deinen Codeausschnitt beinhaltet, könnte wie folgt aussehen:

in diesem Fall (mal angenommen, die Methode sieht wirklich so aus), wäre es doch sinnvoll, die Verarbeitung in der gleichen Klasse ggf. ausgelagert in mehrere private Methoden zu positionieren
und diese Methode würde ich keines Falls der DataTable zuordnen, da diese lediglich zum Speichern der Informationen gedacht ist (wurde es wohl auch nicht, denn dann wäre ein Zugriff auf die Datensätze mittels "this[ i ]" nötig gewesen)

anderes Beispiel:
man hat eine Liste von Zahlen und je nach Zahl soll etwas anderes passieren (Fehlermeldung ausgeben lassen, Ton abspielen oder die nächste Zahl ignorieren)
mir würde da auch nicht im Traum einfallen, der Zahl die Abarbeitung ihrer selbst zu überlassen

Zitat von »Spiele Programmierer«

Aber ich glaube kaum, dass man, wenn man eine rückläufige Schleife findet, einen Blick auf die Dokumentation auf alle enthaltenen Befehle wirft.

wäre eine der verwendeten Methoden eine mit "Remove" im Namen, wäre das auch nicht notwendig

Zitat von »Spiele Programmierer«

Zitat

Guter Code braucht keine Kommentare

Schlechter Code braucht auch keine Kommentare.
Nützlich wären sie trotzdem.

Was noch schlechter ist als schlechter Code mit Kommentar, das ist schlechter Code ohne Kommentar. Richtig wäre hier: guter Code. Punkt. Wirklich guter Code braucht eben keine Kommentare.

Zitat von »babelfish«

Ach, da liegt das Problem.

Nochmal: Lieber schlechten Code vermeiden und guten, selbsterklärenden Code schreiben, als schlechten Code zu kommentieren.

Hab's zitiert, weil's so schön war. Ganz genau so ist es. Kommentare sind nichts böses, aber sie sind theoretisch nur dann nötig, wenn sie eben nötig sind. Und das ist genau dann, wenn der Code nicht selbst-erklärend ist. Und genau dann ist Code eben schlecht.

Zitat von »Sacaldur«

Zitat von »Spiele Programmierer«

Aber ich glaube kaum, dass man, wenn man eine rückläufige Schleife findet, einen Blick auf die Dokumentation auf alle enthaltenen Befehle wirft.

wäre eine der verwendeten Methoden eine mit "Remove" im Namen, wäre das auch nicht notwendig

Genau das. "Process" sagt gar nichts aus. Gar nichts. Da kann alles mögliche passieren. Sollte es aber nicht. Guter Code würde eher sowas machen:
Da braucht man jetzt auch keinen Kommentar mehr. Es ist ersichtlich, was passiert.
Mal ganz davon abgesehen, dass ein Datensatz in einer Tabelle, wie Sacaldur schon sagte, eigentlich nichts "processen" sollte. Das ist Business-Logik, die da im Normalfall irgendwie nicht ganz hingehört.

Ehrlich gesagt find ich schlechten Code mit Kommentaren in der Regel noch schlechter als schlechten Code ohne Kommentare. Letzterer ist zumindest besser lesbar...

Zitat

das ändert aber nichts daran, dass ein Datensatz sich nciht selbst verarbeiten sollte

Ist bisschen komisch, hast recht. Der Code war auch bloß rasch zur Demonstration aus den Findern gesaugt.
Ändert aber nichts an der Problematik. Das wäre dann also besser?:
DataTable.ProcessAt(i);

Zitat

die Verarbeitung in der gleichen Klasse ggf. ausgelagert in mehrere private Methoden zu positionieren

Was meinst du?

Zitat

mir würde da auch nicht im Traum einfallen, der Zahl die Abarbeitung ihrer selbst zu überlassen

Angenommen das mit dem Ton, den Zahlen, usw. wäre zb. ein Teil eines Spieles.

Wenn du jetzt manchmal genau das Ereignis zu einer bestimmten Zahl brauchst und manchmal zu mehreren?
Dann würdest du doppelt programmieren, oder wie stellst du dir das vor?

Hehe. Glaub mir, dot, wenn Du das sehen würdest, was ich manchmal auf Arbeit sehe, da wärst Du froh über ein Quäntchen Kommentare. Speziell dann, wenn da tausend Konstanten (als Zahl natürlich, nicht mit Namen) verwendet werden, ohne dass man weiß, welche wofür steht. (Statemachines mit 20 States, welche nur aus Zahlen bestehen, immer wieder schön, wenn sie in Kombination mit HardwareIds und Hardware-Parametern verwendet werden, die ebenfalls alles nur konkrete Zahlen sind)

Zitat

Wirklich guter Code braucht eben keine Kommentare.

Nein, eben nicht.
Kaum Kommentare, aber nicht keine.

Ganz anderes Beispiel:
In der Lowlevel Programmierung in C oder gar Asm.
Da gibt es immerwieder Stellen die man ohne außreichend kommentierung nur sehr schwer versteht oder man sich erst durch irgendwelche Spezifikationen, Dokumentationen, etc. wühlen müsste.

Zitat

Was noch schlechter ist als schlechter Code mit Kommentar, das ist schlechter Code ohne Kommentar. Richtig wäre hier: guter Code. Punkt.

Ja natürlich. Wir sind und also einig.
Aber den springenden Punkt hast du vergessen:
schlechter unkommentierter Code < schlechter kommentierter Code < guter unkommentierter Code < guter kommentierter Code

Zitat

Guter Code würde eher sowas machen...

Aber wenn Datensätze eben auch aufgeteilt werden müssen?

Wenn du das auch noch so direkt implementierst wird es schnell unübersichtlich. Und gerade dann ist ein Hinweis am Kopf der Schleife warum gerade rückläufig erst recht sinnvoll.
Außerdem wird dieses Process in genau der Form eben auch noch wo anderes gebraucht. Soll ich deiner Meinung das etwa an zehn verschiedenen Stellen implementieren? Und wenn dann ein neuer Verarbeitungsmodus hinzukommt, soll ich das an x verschiedenen Stellen ändern?

Dann sind solche Variablen natürlich auch einfach Overhead denn es nicht braucht.

EDIT: Irgendwie hat er das abgeschickt, obwohl ich noch nicht fertig war.

Zitat von »Spiele Programmierer«

Zitat

das ändert aber nichts daran, dass ein Datensatz sich nciht selbst verarbeiten sollte

Ist bisschen komisch, hast recht. Der Code war auch bloß rasch zur Demonstration aus den Findern gesaugt.
Ändert aber nichts an der Problematik. Das wäre dann also besser?:
DataTable.ProcessAt(i);

Zitat von »Sacaldur«

und diese Methode würde ich keines Falls der DataTable zuordnen, [...]

zusammengefasst: nein

Zitat von »Spiele Programmierer«

Zitat

die Verarbeitung in der gleichen Klasse ggf. ausgelagert in mehrere private Methoden zu positionieren

Was meinst du?

die Methode, wie sie um den Codeschnipsel von dir aussehen könnte (in meinem Beitrag zu sehen) dürfte sich, weil wegen Objektorientierung, innerhalb einer Klasse befinden
da mir kein geeigneter Name eingefallen ist, habe ich diese Klasse vorerst außen vor gelassen, aber nehmen wir mal an, sie heißt "DataProcessor"
diese beinhaltet die Methode, die als Parameter die Tabelle erhält
dann würde ich den Code für die Verarbeitung auch irgendwo innerhalb dieser Klasse ("DataProcessor") ansiedeln - entweder in der gleichen Methode oder ausgelagert in mehrere private Methoden (alles innerhalb von "DataProcessor)

Zitat von »Spiele Programmierer«

Zitat

mir würde da auch nicht im Traum einfallen, der Zahl die Abarbeitung ihrer selbst zu überlassen

Angenommen das mit dem Ton, den Zahlen, usw. wäre zb. ein Teil eines Spieles.

Wenn du jetzt manchmal genau das Ereignis zu einer bestimmten Zahl brauchst und manchmal zu mehreren?
Dann würdest du doppelt programmieren, oder wie stellst du dir das vor?

da Zahlen an sich vielleicht nicht unbedingt das beste Beispiel sind, kann man sich auch eine Skriptdatei (Sammlung einfacher Befehle) vorsstellen
diese könnte an den Zeilenenden aufgesplittet worden sein, wodurch man eine Liste aller Befehle erhält
der Befehl selbst (die Zeichenkette) sollte nicht wissen, was er letztendlich bewirkt
diese Auswertung sollte von einem anderen Objekt - für die gesamte Liste/das gesamte Skript - vorgenommen werden

Zitat von »Spiele Programmierer«

Zitat

Wirklich guter Code braucht eben keine Kommentare.

Nein, eben nicht.
Kaum Kommentare, aber nicht keine.

Nein, er braucht gar keine. "Braucht" ist hier das Schlüsselwort. Er braucht keine, sie sind nicht notwendig.

Zitat von »Spiele Programmierer«

Ganz anderes Beispiel:
In der Lowlevel Programmierung in C oder gar Asm.

Asm ist keine Hochsprache und daher lasse ich das außen vor. Asm ist nicht selbst-erklärend. C jedoch schon, wenn man alles korrekt benennt und kapselt.

Zitat von »Spiele Programmierer«

Da gibt es immerwieder Stellen die man ohne außreichend kommentierung nur sehr schwer versteht oder man sich erst durch irgendwelche Spezifikationen, Dokumentationen, etc. wühlen müsste.

Nein. Falsch. Guter Code macht Dokumentation nicht überflüssig, Spezifikation ebenfalls nicht. Aber er macht Kommentare überflüssig. Dokumentation = was gibt es und wofür ist es da. Spezifikation = was soll wie funktionieren. Kommentar = Deodorant für schlechten und unverständlichen Code.

Zitat von »Spiele Programmierer«

Ja natürlich. Wir sind und also einig.
Aber den springenden Punkt hast du vergessen:
schlechter unkommentierter Code < schlechter kommentierter Code < guter unkommentierter Code < guter kommentierter Code

Nein, den Punkt habe ich nicht vergessen. Guter, kommentierter Code ist nicht besser als guter, unkommentierter Code. Kein Stück.

Zitat von »Spiele Programmierer«

Zitat

Guter Code würde eher sowas machen...

Aber wenn Datensätze eben auch aufgeteilt werden müssen?

Wenn Datensätze aufgeteilt werden müssten, dann hat das ebenfalls gekapselt zu erfolgen. Aber nicht aus dem Datensatz heraus. Ein Datensatz sollte niemals entscheiden dürfen, dass er sich in mehrere Datensätze aufzuspalten hat oder gelöscht werden muss. Das ist nicht im Befugnisbereich des Datensatzes. Ein Datensatz enthält einen Satz Daten, keine Business-Logik.

Zitat von »Spiele Programmierer«

Wenn du das auch noch so direkt implementierst wird es schnell unübersichtlich. Und gerade dann ist ein Hinweis am Kopf der Schleife warum gerade rückläufig erst recht sinnvoll.

Nein, dann ist der Code schlicht schlecht. Ein Hinweis per Kommentar würde versuchen das zu verdecken oder bunt zu malen, aber das Problem würde bleiben: Schlechter Entwurf, schlechter Code.

Zitat von »Spiele Programmierer«

Außerdem wird dieses Process in genau der Form eben auch noch wo anderes gebraucht. Soll ich deiner Meinung das etwa an zehn verschiedenen Stellen implementieren? Und wenn dann ein neuer Verarbeitungsmodus hinzukommt, soll ich das an x verschiedenen Stellen ändern?

Nein, dann kapselst Du das Verhalten - aber nicht als Methode des Datensatzen, denn es bleibt aber dabei: ein Datensatz hat die Einträge der ihm überliegenden Datenstruktur nicht anzufassen. Das geht ihn nichts an, ist nicht sein Metier, nicht sein Bier.

Zitat von »Spiele Programmierer«

schlechter unkommentierter Code < schlechter kommentierter Code < guter unkommentierter Code < guter dokommentierter Code

nur um die Begrifflichkeiten zu klären:
mit Dokumentation ist in ein Stück Text gemeint, der sich in der Regel außerhalb des Codes befindet
bei einigen Sprachen ist es aber vorgesehen oder durch Tools nachträglich möglich, aus Kommentaren mit einer ganz bestimmten Form (in C# Kommentare, die mit /// beginnen, in Java Kommentare, die mit /** beginnen und mit */ enden, ...) eine Dokumentation zu generieren - entsprechende Kommentare würde ich als Dokumentation bezeichnen
mit Kommentaren meine ich (vermutlich auch die anderen) solche Quelltextkommentare, die nicht temporär Code entfernen sollten, keine temporären Notizen darstellen (wie ein "TODO") und aus denen keine Dokumentation generiert wird

das (grobe) "Was?" wird von der Dokumentation abgedekt
das "Wie?" sollte nicht von Kommentaren abgedeckt werden müssen

vielleicht hast du die Aussage nicht ganz richtig verstanden, aber die anderen meinen mit "guter Code benötigt keine Kommentare" so viel wie "guten Code versteht man auch ohne Kommentare"
und die Schlussvolgerung daraus kann sein: wofür Kommentare, wenn diese keinen Mehrwert bringen? (man versteht den Code auch ohne sie)


aber mal zum eigentlichen Thema:
auf Arbeit sind alle Kommentare (oder eher die Kommentare, die in eine Dokumentation umgewandelt werden) auf deutsch, genauso wie alle Variablen, Klassen etc. (interne Vorgabe)
privat wiederum bemühe ich mich, wirklich alles in englisch zu machen, auch wenn den meisten Code niemand zu Gesicht bekommen wird (und ich den meisten Code nicht dokumentiere, aber das ist etwas anderes )