Kommentieren, wieviel ist gesund?

Übersicht BlitzMax, BlitzMax NG Allgemein

Neue Antwort erstellen

DaysShadow

Betreff: Kommentieren, wieviel ist gesund?

BeitragMi, Dez 09, 2009 13:19
Antworten mit Zitat
Benutzer-Profile anzeigen
Hi,

Ich gelange momentan öfter mal in die Situation dass ich mir meinen Code anschaue und mich frage: Was mache ich da?
Bisher kommentiere ich nicht, ich denke aber dass es Zeit ist es sich anzueignen.

Jetzt zur Frage, was soll ich kommentieren, wieviel ist nötig, wo ist es nicht nötig?
Schleifen mit ihrer Funktion kommentieren? Variablen kommentieren sofern sich ihr Nutzen nicht aus ihrem Namen schließen lässt(wobei man dann wohl besser benennen sollte)?

Wieviel ist gesund? Wink

Danke schonmal
MfG DaysShadow
Blessed is the mind too small for doubt

Skabus

BeitragMi, Dez 09, 2009 13:47
Antworten mit Zitat
Benutzer-Profile anzeigen
Hm ich hab mir von Anfnag an angewöhnt meinen Code auszukommentieren, allerdings gehör ich zu der Sorte die zuviel auskommentieren...

Wichtig ist dabei Dinge zu erklären, die sowohl für dich als auch für
evtl. Mitarbeiter nicht ersichtlich ist.
Vor allem Funktionen und Variablen haben die Angewohnheit nicht immer 100%tig sinnvoll zu erscheinen...

Bei mir sind viele Variablen so nach dem Prinzip "ach hier noch ne Variable und da noch eine, besser noch eine" und dann wirds
langsam notwenidg hinzuschreiben was die Variablen denn nun
genau speichern.

Funktionen sollte man IMMER kommentieren, es sei denn
es ist eine elementare Funktion wie "berechnePythagoras" oder
sowas.

Das wichtigste am Kommentieren ist imo aber, dass man NICHT
hinschreibt WAS die entsprechende Stelle tut, sondern warum.

Quasi so:

Zitat:


schlechtes Kommentar:

'diese Variable speichert einen X-Wert
myXValue:Int

besser:
'diese Variable speichert den X-Position des Bildes
myXValue:Int

noch besser:

'diese Variable speichert den X-Position des Bildes
picXPos:Int



Wichtig ist außerdem nicht nur das kommentieren, sondern
vor allem Variablen SINNVOLL zu bennenen.

Die meisten von denen ich hier im Forum Code durchgearbeitet
habe schreiben so geile Definitionen wie:

Zitat:


'Variablen
d:Int
pX:Int
c:Float
x:String
.
.
.
etc...

'Funktionen

Function ab:Int(a:Int)

'Anweisung

End Function



Sowas kann keine Sau lesen, geschweige denn verwalten.
Und drei Monate später weiß keiner(inklusive des Urhebers selbst)
mehr welche Variable und welche Funktion was machen und vor allem WARUM...

Wenn jeder seine Projekte von Anfnag an gut kommentieren würde, dann gäbe es sicher mindestens 30% mehr fertige
Projekte.

Na dann wünsch kich frühliches Kommentieren Smile

MfG Ska
"In einer so verrückten Welt, kann man um in ihr zu überleben nur eines tun, nämlich eben jenes werden: Ein Verrückter!" -Selbstzitat

aktuelles Projekt: Aves Certim - Der Galgen ist nicht weit!
Ein SNES-RPG mit Handels- und Wirtschaftselemente.
Infos?Hier: http://www.blitzforum.de/worklogs/234/
Besucht meine Seite:
www.seelenfriedhof.de.vu
 

n-Halbleiter

BeitragMi, Dez 09, 2009 15:13
Antworten mit Zitat
Benutzer-Profile anzeigen
So in etwa würde ich dir das auch Raten, allerdings ist meiner Meinung nach noch Ungarische Notation zu empfehlen, da damit schon bei der Namensgebung von Variablen und Funktionen ein Teil deines Problems abgedeckt werden dürfte. Am Anfang sieht es etwas kryptisch aus, aber man gewöhnt sich ziemlich schnell daran.
mfg, Calvin
Maschine: Intel Core2 Duo E6750, 4GB DDR2-Ram, ATI Radeon HD4850, Win 7 x64 und Ubuntu 12.04 64-Bit
Ploing!
Blog

"Die Seele einer jeden Ordnung ist ein großer Papierkorb." - Kurt Tucholsky (09.01.1890 - 21.12.1935)

Tankbuster

BeitragMi, Dez 09, 2009 15:14
Antworten mit Zitat
Benutzer-Profile anzeigen
Noch besser:

Zitat:
'diese Variable speichert die X-Position des Bildes
picXPos:Int


Wink

Also ich habe zwischen meine Funktionen immer 2 Reihen Rauten auskommentiert. (#)
Das liegt daran, dass ich kleine Funktionen meistens nicht einrücke, und man durch den Farblichen unterschied einen besseren Überblick bekommt.
Lange Funktionen kann man auchmal kommentieren. Es ist ziemlich Sinnvoll, wenn man auch die Vorgehensweise nochmal extra ausschreibt.

Außerdem schreibe ich die Variablen so, dass man am Name schon erkennt, für was sie ungefähr stehen. Bei einigen, wo es nicht anders geht, schreibe ich bei der deklaration was dahinter, aber sonst eigentlich nie.
Twitter
Download Jewel Snake!
Windows|Android

Noobody

BeitragMi, Dez 09, 2009 15:35
Antworten mit Zitat
Benutzer-Profile anzeigen
Ich persönlich halte nicht viel vom Kommentieren - kommentierte Codes sind für mich unübersichtlich und ich finde mich schwer darin zurecht.

Viel wichtiger finde ich es jedoch, dass man Funktionen und Variablen aussagekräftige Namen gibt, damit deren Sinn auf den ersten Blick ersichtlich ist. Von ungarischer Notation würde ich eher abraten, da sie den Code unnötig unleserlich macht und über den eigentlichen Sinn einer Variablen oder Funktion wenig aussagt - der Datentyp sollte ja von einer halbwegs brauchbaren IDE angezeigt werden, wenn man wirklich darauf angewiesen ist. Ich selbst benutze immer noch die MaxIDE, aber persönlich halte ich den Datentyp einer Variablen nicht besonders wichtig, da er aus der Benutzung klar wird.

Ich sah schon sehr viele Codes, die zwar schön kommentiert waren, ich aber trotzdem keine Ahnung hatte, was dort gemacht wurde, da sie schlecht (oder gar nicht) eingerückt waren, aussagelose Bezeichner verwendeten und auch sonst alles sehr umständlich machten. Daher wäre es mir wichtiger, wenn der Code an sich gut leserlich wäre, dafür nicht kommentiert.

Falls du wirklich kommentieren willst, so würde ich vorschlagen, vor jeder Funktion einen Blockkommentar zu machen, der beschreibt, was die Funktion macht und was die einzelnen Parametzer bewirken. In der Funktion selbst würde ich nur schwer verständliche Einheiten dokumentieren, beispielsweise mathematische Formeln oder rekursive Algorithmen. Vermeide aber bitte Überdokumentation, z.B: BlitzMax: [AUSKLAPPEN]
For Local I:Int = 0 To 10 'Von 0 bis 10 iterieren

Local Foo:TBar = New TBar 'Neuen TBar erstellen

Cls() 'Bildschirm löschen

Solche Kommentare bringen niemandem etwas und lenken nur vom wesentlichen ab.
Man is the best computer we can put aboard a spacecraft ... and the only one that can be mass produced with unskilled labor. -- Wernher von Braun

Jan_

Ehemaliger Admin

BeitragMi, Dez 09, 2009 15:55
Antworten mit Zitat
Benutzer-Profile anzeigen
Laut meinem Chef Pro Zeile Code eine komplette erklärung, von allem + auswirkungen auf alles.
+Dokumentation des gesammten mit eingehen auf jede änderung jeder Variable
--> 1ne Zeile Coden 50 Zeilen schreiben.
between angels and insects

Goodjee

BeitragMi, Dez 09, 2009 15:59
Antworten mit Zitat
Benutzer-Profile anzeigen
Jan_ hat Folgendes geschrieben:
Laut meinem Chef Pro Zeile Code eine komplette erklärung, von allem + auswirkungen auf alles.
+Dokumentation des gesammten mit eingehen auf jede änderung jeder Variable
--> 1ne Zeile Coden 50 Zeilen schreiben.


dein chef kann wohl nicht programmieren, ein gewisses grundverständniss von quellcode auch ohne kommentare sollte man wohl voraussetzen können
"Ideen sind keine Coladosen, man kann sie nicht recyclen"-Dr. House
http://deeebian.redio.de/ http://goodjee.redio.de/

Midimaster

BeitragMi, Dez 09, 2009 16:14
Antworten mit Zitat
Benutzer-Profile anzeigen
Da bin ich voll der Meinung von Noobody. Die meisten nutzen nicht die erklärende Kraft der Variablennamen. Bei mir kann dann schon mal sowas wie "locSuchStelle" oder "SirenenSoundVolumen" dastehen. Warum nicht?

Auch in den Funktionen erklärt der Variablenname, welche Parameter übergeben werden:

Function LiedDarstellen(VonTakt%,BisTakt%,AktCursorPos%,AktSongPos%,NotenFarbe%)

Kommentare gibts oft nur, um schnell einen Codeblock wiedezufinden. Hier ein Beispiel dazu. Was soll ich da noch an Kommentaren hinzuschreiben?

Code: [AUSKLAPPEN]
' simulation der Schwerkraft auf einen Ball
Global BallX#, BallY#, BallxSpeed#, BallYSpeed#, Schwerkraft#, BremsWirkung#
Global BildBreit%, BildHoch%, BallRadius%

BildBreit=600
BildHoch=400
BallXSpeed=2
BallRadius=10
Schwerkraft=0.10
BremsWirkung=0.95
Graphics BildBreit,BildHoch

Repeat

     'simulierte Schwerkraft
   BallYSpeed=BallYSpeed+Schwerkraft
   BallX=BallX+BallxSpeed
   Bally=Bally+BallYSpeed
   
   'nur um die Spielränder wirken zu lassen
   If BallX<0 Or BallX>(BildBreit-BallRadius)+1 Then
      BallxSpeed=-BallXSpeed
   EndIf
   If  BallY>(BildHoch-BallRadius) Then
      BallYSpeed=-BallYSpeed*BremsWirkung
      BallXSpeed=BallXSpeed*BremsWirkung
      BallY=BildHoch-BallRadius
   EndIf

     ' das Malen
   Cls
   DrawOval BallX,Bally,BallRadius,BallRadius   
   Flip

Until KeyHit(Key_escape)



wichtig finde ich den Einsatz von Leerzeilen, sie helfen die Codeblocks auseinanderzuhalten. So habe ich mir angewöhnt, zwischen zwei Functions immer 4 Leerzeilen zu lassen. Beim schneller Scrollen in 1000 Zeilen Code siehtst Du dann diese Lücken.

Konsequent verwende ich auch deutsche Variablen- und Funktionsnamen, um meinen Code von Codeschnippsel dritter auseinaderzuhalten.

DaysShadow

BeitragMi, Dez 09, 2009 17:42
Antworten mit Zitat
Benutzer-Profile anzeigen
Dankeschön für die zahlreichen Antworten.

Also Variablen benenne ich schon sinnvoll so wie Midimaster es beschreibt, nur halt durchweg in Englisch, sowas wie z.B. d:Float kommt mir nicht unter, auch die Namen der Funktionen oder Methoden beschreiben an sich schon grob ihre Funktion, ich werde dann mal schauen dass ich an bestimmten Stellen vielleicht einfach die Funktion des Codes länger beschreibe, wenn es nicht etwas ganz banales ist.

Ungarische Notation werde ich nicht verwenden, da ihre Nutzung so oder so auch schon seit längerem nicht mehr empfohlen wird und ich persönlich auch keinen direkten Nutzen sehe und es eher verwirrend finde, aber das ist sicher auch Geschmackssache.

Als ich anfangen wollte zu kommentieren tat ich nämlich genau das was Noobody als falsch und überflüssig beschrieben hat, Zeile für Zeile kommentieren auch wenn die Dinge noch so banal sind wie bei Midimasters Beispiel, das kam mir allerdings bald schon seltsam vor und half mir auch nicht beim Lesen des Codes, daher der Thread.

Für weitere Anregungen bin ich natürlich stets offen Wink

MfG DaysShadow
Blessed is the mind too small for doubt
 

Ava

Gast

BeitragMi, Dez 09, 2009 18:02
Antworten mit Zitat
Eine aussagekräftige Bennenung reicht meiner Meinung und Erfahrung nach auch volkommen aus. Kommentare füge ich nur als kleine Notizen ein, um bspw. Stellen zu markieren, die ich später noch erweitern oder etwas optimieren muss (dann aber auch niemals direkt hinter dem Code, sondern immer als seperater "Notizblock" über dem Codeabschnitt). Hin und wieder kann auch eine kleine Notiz bei einem sehr komplexen Codeblock hilfreich sein (mir ist es schon öfter passiert, dass ich in ältere Module hineingeschaut habe und dort in guter Absicht angefangen habe, Abschnitte zu optimieren, die ansich genau richtig so waren, wie sie waren Rolling Eyes - und da ich mich kenne und weis, welche Codeabschnitte nach einige Wochen/Monaten bei mir womöglich zu Verwirrung führen könnten, notiere ich mir das dort an diesen Stellen *g* Rolling Eyes)

DaysShadow

BeitragMi, Dez 09, 2009 18:07
Antworten mit Zitat
Benutzer-Profile anzeigen
Hehe, das mit der Verwirrung kenne ich, denke mir dann immer, damals machte es doch noch Sinn...*grml* Wink

Und da ich momentan an etwas schreibe mit dem ich vielleicht noch länger arbeiten werde ist mir eben genau das wichtig dass ich bei möglichen späteren Optimierungen noch weiß worum es da geht und nicht wieder dieselben Grundüberlegungen anstellen muss um herauszufinden wie der Code da tickt.

Aber im Grunde sehe ich das ähnlich, also ebenfalls danke für die Bestätigung.

MfG DaysShadow
Blessed is the mind too small for doubt

Neue Antwort erstellen


Übersicht BlitzMax, BlitzMax NG Allgemein

Gehe zu:

Powered by phpBB © 2001 - 2006, phpBB Group