Hallo Besucher, der Thread wurde 3,9k mal aufgerufen und enthält 27 Antworten

letzter Beitrag von sparhawk am

Macht ihr eigentlich viele Kommentare in selbstgeschriebenen Programmen?

    Ich nutze bei CBM prg Studio die interne Kommentarfunktion in Form von !-- , z. B. um mir bei der Initialisierung von Variablen zu notieren, weichen Wert ea, es$ oder ei% speichern.


    Vor Subroutinen nutze ich !--, um Parameter und Funktionsweise zu beschreiben.


    Der Vorteil ist, dass diese Kommentare nicht mitkompiliert werden und ich eine Menge RAM spare.


    Außerdem nutze ich "indirekte Kommentare", indem ich zusammenhängende Codeblöcke in einzelne Dateien packe und diese dementsprechend benenne. Beispiele wären hier: 00000 - Initialisierung.bas oder 00250 - Subroutinen.bas. CBM prg Studio macht daraus dann ein Komplettlisting und ich weiß immer, wo ich was finde.


    Also ja, ich kommentiere viel, wenn ich in BASIC programmiere. Bei meinem echten Job als Webentwickler bin ich da aber etwas schluddrig und versuche so zu programmieren, dass ich es noch Monate später lesen kann. Klappt aber nicht immer... :D

    Da hier nicht explizit nach Basic Programmen gefragt wurde, gebe ich meinen Senf auch mal dazu...
    ich bin relativ neu in Sachen Programmierung und beschäftige mich zurzeit ich bin relativ neu (4 Jahre) in Sachen Programmierung und beschäftige mich zurzeit ausschließlich mit der C Variante der Arduino IDE.
    Ohne Kommentare würde ich nicht klar kommen, da es sehr häufig passiert, dass man nach einem oder zwei Jahren die Maschine oder das elektronische Bauteil verbessern oder abändern muss.
    Spätestens dann kann ich mir die Zeit die dafür notwendig ist sich in ein Programm einzudenken nicht mehr leisten.


    Praktischerweise stehen dort im Sourcecode ja nicht nur die Variablen sondern auch welche Pins als Ein oder Ausgänge definiert sind. Da eignet sich die Kommentarfunktion hervorragend um im Klartext dazuzuschreiben, um was es sich handelt- und ob der ein bzw Ausgang hi oder lo abgefragt wird.


    Ich denke, wenn ich ich denke, wenn ich jetzt mit dem C64 programmieren würde, müsste ich mir noch viel viel mehr Notizen machen.
    Kommt halt darauf an, wie sehr man sich in der Programmiersprache bereits zu Hause fühlt und ob der source code eine Aneinanderreihung von Buchstaben ist, oder bereits als Bild erscheint.


    Stefan

    Ich bin da leider auch nicht so fleißig. Bei mir sind es eher kleine Anmerkungen im Code. Ich versuche aber die Sachen kurz zu halten und durch die Bezeichner die Sache ein wenig selbsterklärend zu gestalten. Am Ende merke ich doch, dass ein bisschen mehr Text der Sache gut getan hätte. Nach drei Jahren ist es fast als hätte ich fremden Code vor mir.


    Hier mal ein Beispiel von einem alten Win32 Projekt:

    Da im Eingangsposting REM erwähnt wird geht es wohl schon um BASIC, trotzdem schadet eine etwas größere Klammer zu dem Thema sicher nicht :)


    Früher hat man oft gelesen, dass "alles" kommentiert sein sollte. Das halte ich nicht (mehr) für sinnvoll. Hier ein paar Thesen dazu, die ich für richtig halte:


    • Sauberer, lesbarer und strukturierter Code macht die meisten Kommentare überflüssig. Was man wirklich tun sollte ist, sich Gedanken über die Struktur eines Programms zu machen. Module (bei Verwendung von OOP Klassen) sollten nur inhaltlich zusammenhängende Funktionen enthalten. Funktionen sollten kurz sein und nur genau eine Sache erledigen. Die Namen von Funktionen sollten genau beschreiben, was diese Funktion tut. Variablennamen sollten ihren Inhalt beschreiben. Der Code sollte keine "magic numbers" enthalten, stattdessen werden solche Werte ebenfalls sprechend benannt (z.B. als Konstanten, Macros, was auch immer die Sprache dafür bietet). Das geht in der Regel sogar für einzelne Bits. Wenn man sich an all das hält bleibt normalerweise sehr wenig übrig, was nicht selbsterklärend ist.
    • Überflüssige Kommentare stören statt zu helfen. Wenn ich PRINT"HELLO, WORLD" schreibe, und dazu kommentiere, dass das jetzt "HELLO, WORLD" ausgibt, muss sich der Leser des Programms nur durch Mist wühlen, den er eh schon weiß. Wenn in einem OOP-Projekt eine Klasse eine Property Name hat, ist ein Kommentar "The name" ebenfalls nur störend. Letzteres sieht man gerne in Projekten, bei denen in der Coding Guideline steht, dass jede public Property kommentiert sein muss. Solche Guidelines sollte man für die Lesbarkeit des Codes besser abschaffen.
    • Ein guter Kommentar erklärt das "warum", nie das "was" und "wie". Wenn man sich an die Regeln aus (1) hält ist für jeden Leser an jeder Stelle offensichtlich, was der Code tut. Es wird aber immer mal wieder Stellen geben, an denen nicht unbedingt klar ist, warum etwas getan wird. Genau das sind die Stellen, die dann wirklich Kommentare brauchen -- das sind meistens auch die Stellen, an denen man selbst als Autor des Programms später rätselt, falls man hier nicht kommentiert hat.


    Leider lässt sich das alles nicht unbedingt aufs Programmieren in COMMODORE BASIC übertragen. Der Sprache fehlt fast alles, um wie unter (1) erklärt "selbsterklärenden" Code zu schreiben. Viele Möglichkeiten zur Strukturierung gibt es nicht, Variablennamen haben maximal zwei Zeichen (man kann längere schreiben, aber das empfiehlt sich nicht, da es a) Ausführungszeit kostet und b) das Risiko birgt, dass aus Versehen zwei "verschiedene" Variablen tatsächlich die gleiche Variable sind), alle Variablen sind global, usw. Da klingt es zunächst einmal sinnvoll, dafür mehr zu kommentieren.


    Kommentare in BASIC sind aber auch problematisch -- sie brauchen Platz im Speicher und dummerweise auch Zeit bei der Ausführung des Programms. Beides ist auf einem C64 knapp und wertvoll. Ich würde empfehlen, in BASIC komplett auf Kommentare zu verzichten.


    Damit das Programm trotzdem verständlich bleibt gibt es zumindest ein paar Dinge, die man tun kann:

    • Eine gewisse Strukturierung kann man über die Zeilennummern erreichen -- eine "Funktion" (in sich abgeschlossene Logik) belegt z.B. die Zeilen von 500-599, eine andere die von 600-699.
    • Diese Blöcke kann man außerhalb (z.B. in einem weiteren Dokument, zur not auch mit Stift und Papier) dokumentieren -- da wird dann erklärt, was dieser Block tut.
    • Da alle Variablen global sind und sprechende Namen quasi ausgeschlossen sind bietet sich zusätzlich ein "Variablenverzeichnis" an, ebenfalls in einem separaten Dokument geführt. Da wird zu jeder Variable erklärt, was sie bedeutet und wo und wie sie verwendet wird.

    Bei mir kommt es drauf an in welcher Sprache ich programmiere. In Python schreibe ich fast nie Kommentare, und wenn dann nur zur Uebersichtlichkeit oder wenn ich da wirklich etwas mache, wo ich von vorneherein schon weiss, dass ich mich irgendwann fragen werde, warum ich das so getan habe. Also Dinge, die man aus dem Code wirklich nicht rauslesen kann, die schreibe ich dann schon dahinter. Das halte ich fuer absolut essentiell.


    In Assembler schreibe ich deutlich oefter Kommentare, teilweise schreibe ich die auch schon bevor ich den eigentlichen Code schreibe. Wenn ich z.B. den Kollisions-Check der Spielfigur mit der Wand mache, dann schreibe ich als Kommentar "collision check player vs wall" oder sowas, und darunter kommen dann vielleicht 10-20 Zeilen Assembler-Code. Dann kommt wieder der naechste Kommentar und die naechsten 10-20 Zeilen Code. Denn Assembler-Code ist ja an sich meist sehr stark von dem entfernt, was eigentlich im Programm passiert, daher finde ich es schoen, immer alle paar Zeilen zu wissen, was die drunterliegenden Statements eigentlich fuer einen Zweck haben.

    Ich habe früher meinen Code nur sehr mäßig und müßig kommentiert...
    Heute allerdings überwinde ich meine Trägheit und kommentiere fleißig aber nicht ausufernd.
    Wenn man noch jung ist, sieht man in der Regel keinen prägnanten Bedarf. Aber nach einiger Zeit ist es definitiv hilfreich, wenn man kommentiert.


    Sprechende Bezeichner sind auch überaus hilfreich...

    Zitat von daybyter

    Ich mach in vielen Sprachen diese javadoc Kommentare, weil ich mich so dran gewöhnt hab.

    Wir verwenden Doxygen für C und C++, das ist sehr ähnlich wie javadoc.
    Das mache ich auch bei privaten Projekten so.


    Wichtig finde ich auch den Header, der sollte schon beschreiben, was da drinnen im File zu finden ist.


    Bei komplizierten Codestellen (die mal eigentlich vermeiden soll), kann man schon mal ein paar Kommentare mitten im Code stehen haben.
    Damit man weiß wie ein Algorithmus funktioniert. Ich habe da schon Codestellen programmiert, die mehr Kommentare als Code enthalten haben.

    Ich denke, wenn Klassen, Methoden und Variablen sprechende Namen haben kann man den Code in der Regel schon ganz gut lesen.


    Ich bin auch ganz ehrlich ein Dokumentationsmuffel.


    Lässt sich allerdings tatsächlich schlecht auf Basic übertragen.

    Zitat von ZeHa

    In Assembler schreibe ich deutlich oefter Kommentare

    Assembler ist schon noch ein Sonderfall, da ist leider oft nicht auf den ersten Blick offensichtlich, was der Code tut. Allerdings kann man selbst da einiges "selbsterklärend" machen -- mit einem modernen Assembler wie z.B. ca65 kann man auch "Module" bauen, die später gelinkt werden, es gibt Scopes und "Prozeduren", man kann Hardwareregister benennen (ein lda VIC_RASTER sagt mir mehr als ein lda $d012), usw. -- trotzdem tun da ein paar mehr Kommentare sicher gut :)

    Ich fange gerade erst mit Swift an. In dem Einsteigerbuch wird empfohlen, dass man die Kommentarfunktion nutzen sollte, um sich späteres reindenken zu erleichtern. Zudem ist es für mich eine Stütze beim lernen. Denn ich vergesse, wegen der langen Phasen in denen ich mich nicht mit Swift-lernen beschäftigen kann, ziemlich schnell.


    So will ich mir es erst gar nicht abgewöhnen. Die Frage ist natürlich, ob ich es selbst für nötig halten werde, sobald ich alles besser verinnerlicht habe. Da werde ich bestimmt auch noch schreibfaul.

    Zitat von enthusi

    oh, da finde ich GERADE $d012 hilfreicher.

    Nur, solange du ALLE Hardware-Register der Maschine kennst. $d012 war ein sehr banales Beispiel, das kennt jeder. Aber was war gleich DC04? D025? ... ;)

    Zitat von enthusi

    Allein schon beim debuggen im monitor oder dergleichen (jaja, man kann da auch labels laden).

    Genau das. Und wenn du das NICHT machst, siehst du in dem Fall eben $d012. Ist ja auch kein Problem WENN du das Register kennst :)

    Also ich verwende bei z.B. $D020 und $D021 lieber die Nummern, aber die kennt ja wirklich jeder. Aber bei anderen verwende ich entweder einen Alias, ODER wenn ich es eh nur an 1 oder 2 Stellen brauche, schreibe ich einfach auch nen Kommentar hin, z.B. "enable multicolor mode" und dann eben das dazu passende LDA/STA-Paar darunter. Dann weiss ich was da passiert und weiss die Adressen vielleicht auch irgendwann mit auswendig.


    Was das Lernen angeht, @Maxresdefault, finde ich es vollkommen in Ordnung, viele Kommentare zu verwenden. Da finde ich noch nichtmal einen "gibt HALLO auf dem Bildschirm aus"-Kommentar schlimm hinter einem "10 PRINT 'HALLO'", denn hier geht es ja ums Lernen. Wenn Du aber mal routiniert programmierst, wirst Du automatisch merken, dass Du viele Kommentare nicht mehr brauchst. Genauso wie Du beim Autofahren ja auch irgendwann weisst, welches Pedal wo ist und welcher Gang wie reingeht usw. Trotzdem hast Du anfangs den Fahrlehrer neben Dir sitzen der Dir alles im Detail sagt.

    Ich kommentiere reichlich. Es dauert nicht lang, bis man vor seinen eigenen Programmen steht, als ob jemand anderes sie programmiert hätte.


    Wenn auf der Arbeit was "frisches" gemacht wird, dann beschreibe ich zumindest:
    -den Sinn von Unterprogrammen, Beschreibung zu wenig offensichtlichen Parametern.
    -Was die Anfrage war, wer sie wann gestellt hat, und warum die Anfrage Sinn macht,
    -"schwierigere" Entscheidungen für ein Vorgehen,
    -Überschriften für Variablenblöcke wie "Für den Vergleich mit dem letzten Datenexport"
    -kleine Zwischenüberschriften wie "Kistendaten holen" für späteres schnelleres Auffinden von interessanten Stellen,
    -EXIT-Befehle sind auch deutlich markiert.


    Bei Änderungen:
    -Datum, Sinn, wer es angefordert hat/was das eigentlich Problem war.
    -In der Regel betreffen Änderungen nur wenige Zeilen. Die alte Version bleibt auskommentiert zurück!
    Versionskontrolle ist zwar hier sehr hilfreich, um beim Ein. und Ausschecken die Unterschiede präsentiert zu bekommen, aber im Kontext des Quelltextes kann man ein bisschen mehr hinterlassen.
    -welche Bugs jemand immer wieder macht,
    -welche Anforderungen sich immer wieder geändert haben
    -welche tollen Verbesserungen man schnell wieder verworfen hat.
    Der nächste, der an der Stelle arbeitet, wird das schon verstehen.


    Zu Zeiten von C64-Assembler oder gar Basic war das aber alles sehr eingeschränkt.
    Macht das Lesen von ewig alten Quelltexten nicht einfacher...

    Ich versuche unabhängig von Kommentaren die Pfadfinder-Regel anzuwenden: jedes mal wenn ich am code arbeite ihn etwas besser zu verlassen als ich ihn vorfand.

    Es gibt zwei Varianten:


    a) Ja, viele Kommentare oder ganze Erklärungen, wozu ein Abschnitt oder eine Funktion überhaupt gut ist, wenn es jemand anderes oder auch ich selbst mal später verstehen soll.


    b) Nein, wenn es niemand und man selbst später auch nicht verstehen soll, lässt man die Kommentare weg und schreibt alles in eine Zeile.


    Bevorzugt ist für mich Variante a). Bei b) finde ich es alleine deshalb schon nicht sinnvoll, da die investierte Energie später verloren ist, wenn man es nochmal anfassen will. Dann kann man auch von vorne anfangen. Macht für mich keinen allgemeinen Sinn.