Entwickler-Ecke
Sonstiges (Delphi) - Wie mache ich am besten Kommentare?
sneki - Mo 15.03.10 12:05
Titel: Wie mache ich am besten Kommentare?
Hallo!
Ich bin grade dabei den Quelltext für mein Programm mit Kommentaren zu versehen, nur mein Lehrer meint ich soll sie mgölichst kurz halten, nur ich weiß nicht was ich genau falsch mache (Frauenproblem: viel reden und es nicht merken)
Hier mal ein Auszug meiner bisherigen Kommentierarbeit:
Delphi-Quelltext
1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24:
| Rezept1 = record Name: string; Zutat1: string; Zutat2: string; Zutat3: string; Zutat4: string; Anzwert: Integer; end;
Rezept2 = record Name: string; Anleitung: string; end;
const Kirsche='Kirsche'; Kokos='Kokos'; Nuss='Nuss'; Schoko='Schokolade'; |
Delphi-Quelltext
1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23:
| if Checkbox1.Checked=true then begin for i:=1 to 20 do begin if rmz[i].Anzwert=0 then begin if rmz[i].Zutat1=Kirsche then begin for k:=1 to 20 do begin if rmz[i].Name = ran[k].Name then Listbox1.Items.Add(ran[k].Name ) end; rmz[i].Anzwert:=1; end; end; end; end; |
ist das wirklich zu viel?? wo ist das kommentieren unnötig?? ich weiß nicht was ich weglassen muss :( mache sowas aber auch zum ersten mal, also das kommentieren....
würde mich über schnelle Hilfe freuen xD
Gausi - Mo 15.03.10 12:15
Hallo,
Ich bin der Meinung: Lieber zuviel Kommentare, als zu wenig. ;-)
Trotzdem lässt sich bei dir etwas optimieren, denke ich. Zum Beispiel: Warum heißt die Checkbox "CheckBox1"? Da lässt sich doch bestimmt ein besserer Name finden. Dann kann man sich den Kommentar darüber evtl. schon sparen, weil aus den Bezeichnern direkt der Sinn klar wird. Auch "Rezept1" und "Rezept2" sind meiner Meinung nach nicht so ganz optimal.
Und evtl. den Code anders einrücken, dann liest sich das flüssiger:
Delphi-Quelltext
1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11:
| if Checkbox1.Checked then begin for i:=1 to 20 do begin if rmz[i].Anzwert=0 then begin if rmz[i].Zutat1=Kirsche then begin ... |
jaenicke - Mo 15.03.10 12:45
Grundsätzlich sollten Kommentare vermieden werden, die sich rein auf eine programmiertechnische Sache beziehen (außer wenn es gerade darum geht, schließlich lernt ihr das ja erst). Zum Beispiel dass du eine Variable vergleichst. Das ist uninteressant, das sieht man ohnehin.
Wichtig ist was du damit bezwecken willst. Bei dir z.B. steht "Vergleich des Rezeptnamen mit dem der ran-Variablen". Es reicht hier (und bringt auch mehr), wenn du die ganze Schleife beschreibst. Dass du nämlich, wenn die Zutat im aktuellen Rezept drin ist und in ran steht das Rezept in die ListBox packst. Das beschreibt kurz die ganze Schleife ohne in die Details der Umsetzung zu gehen.
Dazu ist es aber wie
Gausi auch bereits geschrieben hat unabdingbar die Komponenten usw. gut zu bezeichnen, so dass man daran schon sieht was diese machen. Insbesondere sollten Typen wie deine Records immer mit einem T anfangen, TRezept1 zum Beispiel. Zudem sind solche "magischen Werte" wie bei dir die 0 oder 1 bei dem Anzeigewert unübersichtlich. Dort kannst du entweder sprechende Konstanten benutzen:
Delphi-Quelltext
1: 2: 3: 4: 5: 6: 7: 8:
| const ANZ_REZEPT_NICHT_ANGEZEIGT = 0; ANZ_REZEPT_IN_LISTBOX = 1;
...
if rmz[i].Anzwert = ANZ_REZEPT_NICHT_ANGEZEIGT then ... |
Oder die schönere Lösung, die ihr aber vielleicht noch nicht hattet, mit Sets:
Delphi-Quelltext
1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16:
| type TRezeptAnzeige = (reaNichtAngezeigt, reaInListBoxAngezeigt);
TRezept1 = record Name: string; Zutat1: string; Zutat2: string; Zutat3: string; Zutat4: string; Anzwert: TRezeptAnzeige; end;
...
if rmz[i].Anzwert = reaNichtAngezeigt then ... |
Wobei bei dir auch ein Boolean vielleicht reicht, der einfach nur anzeigt, ob das Rezept angezeigt wird oder nicht.
Delete - Mo 15.03.10 13:10
Benennen die Variablen und Steuerelemente gescheit.
Delphi-Quelltext
1:
| if chkCherries.Checked then |
Schon wird der Kommentar überflüssig.
Und prinzipiell kann man sagen: Wenn du etwas kommentierst, dann das Warum / Weshalb, wenn es aus dem Quellcode nicht ersichtlich wird und nicht das wie. Das Wie sehe ich ja im Quellcode.
Delphi-Quelltext
1: 2:
| begin if rmz[i].Anzwert=0 then |
Das sehe ich doch, dass auf null geprüft wird.
Des weiteren kann auch häufig auf Kommentare verzichten, in dem man seinen Code neu strukturiert. Zum Beispiel:
Delphi-Quelltext
1:
| if (winmajorver = 5) and (winminorver = 1) then |
So was müsste ich kommentieren, dass ich da uaf Windowx XP prüfe. Deswegen:
Delphi-Quelltext
1: 2: 3: 4:
| function IsWindowsXP: Boolean; begin Result := (winmajorver = 5) and (winminorver = 1); end; |
Und dann:
Schon komme ich ohne Kommentar aus und es ist trotzdem klar, was da passiert.
@Gausi: "Ich bin der Meinung: Lieber zuviel Kommentare, als zu wenig."
Bitte nicht. Wenn der Quellcode mit Kommentaren zu gekleistert ist, stört sehr beim Lesefluss, wenn man den eigentlichen Code lesen will. Desweiteren je mehr Kommentare, desto größer die Wahrscheinlichkeit, dass sie veraltet und/oder einfach falsch sind. Und nichts ist schlimmer als ein veralteter und/oder falscher Kommentar. Und wenn ich mir nicht mehr sicher sein kann, ob ein Kommentar noch aktuell ist bzw. auch stimmt, kann ich gleich alle Kommentare in die Tonne treten.
Siehe dazu auch:
http://www.michael-puff.de/Artikel/CleanCode.shtml
dummzeuch - Mo 15.03.10 23:16
Gausi hat folgendes geschrieben : |
Ich bin der Meinung: Lieber zuviel Kommentare, als zu wenig. ;-)
|
Aber nur, wenn sie auch gepflegt werden. Ein falscher Kommentar ist wesentlich schlimmer als gar keiner. Sourcecode muss gepflegt werden, sonst compiliert/funktioniert das Programm nicht, Kommentare sind dafuer egal und werden deshalb gerne vergessen. Wenn man dann zwei Jahre spaeter einen Kommentar liest, der sich auf laengst geaenderten Code bezieht, der damalige Entwickler laengst die Firma verlassen hat und keiner mehr so genau weiss, was der Code eigentlich sollte, kommt Freude auf.
Deshalb stehe ich auf dem Standpunkt: Wenn man ueberlegt einen Kommentar zu schreiben, um den Code zu erklaeren, sollte man erstmal versuchen, ob man nicht den Code umstrukturieren kann, so dass er selbsterklaerend ist. Typische Massnahmen:
* bessere Variablen-/Funktions-/Prozedurnamen
* Symbolische Konstanten statt Literale
* Ausgliedern eines Codeteils in eine (Sub-)Prozedur
* zusaetzliche Variablen fuer Zwischenergebnisse (mit den passenden Namen natuerlich)
* Habe ich das Entfernen von WITH Statements schon erwaehnt?
Erst wenn das nicht weiterhilft, sollte man moeglichst kurz den Zweck des Codes erklaeren (nicht den Code beschreiben, dafuer sollte der Leser schliesslich die Programmiersprache verstehen)
Wer Kommentare wie ...
... schreibt, der gehoert dafuer geschlagen. Wer als Chef oder QM-Fuzzi Kommentare wie ...
Delphi-Quelltext
1: 2: 3: 4: 5:
| procedure Trallala; |
... verlangt, hat zuviele schlechte Buecher gelesen.
So, und jetzt leg' ich mich wieder hin....
twm
Martok - Di 16.03.10 00:22
Ich habe lange Zeit nichts mehr kommentiert, einfach, weil guter Code selbsterklärend genug ist.
Nur einen gabs vor ein paar Tagen mal, um einen Wegfindungsalgorithmus zu erklären, dessen Implementation durch Optimierungen etwas schlecht lesbar geworden ist. Da kamen dann auf ~120LOC 5 Zeilen Kommentar vorneweg, um den Algo zu beschreiben.
Man muss aber sagen: So kaputten Code, wie er meistens in Schulen gelehrt wird, sollte man kommentieren :lol:
Und ansonsten haben
Luckie und
dummzeuch vollumfänglich Recht.
dummzeuch hat folgendes geschrieben : |
Wer als Chef oder QM-Fuzzi Kommentare wie ...
Delphi-Quelltext 1: 2: 3: 4: 5:
| procedure Trallala; |
... verlangt, hat zuviele schlechte Buecher gelesen. |
... oder noch nie von Versionskontrolle gehört. Wenn man sowas tracken will, hat man dafür die Informationen in den Commits.
Aber das steht ja hier nicht zur Diskussion.
Chemiker - Di 16.03.10 01:19
Hallo,
Ich mache das eigentlich immer so und bin damit bisher ganz gut gefahren. Ich bin grade wieder mehr dabei mit C/C++/Assembler zu arbeiten und bin eigentlich ganz froh das ich vor ca. 20 Jahren so meine Routinen kommentiert habe und finde so schnell Routinen die noch interessant sind.
Ich kann nur Gausi zustimmen besser zu viel als zu wenig. Wenn man im Thema ist bräuchte man eigentlich keinen Kommentar, aber mal den Quellcode lesen, den ihr vor 10 Jahren geschrieben habt. Dann wird meiner Meinung ganz schnell klar, ob nicht mehr Kommentar sinnvoller gewesen wäre.
Bis bald Chemiker
jasocul - Di 16.03.10 09:06
Ich schreibe nur wenig Kommentare in den Source.
Meistens ist der Source selbsterklärend und Bedarf keines Kommentares.
Ausnahmen:
- Komplexere Bedingungsabfragen bekommen schon mal einen Hinweis, was da geprüft wird.
- Wenn ich Sourcen eines anderen Autors verändere, damit dieser die Veränderungen schneller erkennen kann bei der Gegenkontrolle. Immer mit Datum und Namen versehen und was geändert wurde.
- Strukturen die etwas länger oder verschachtelt sind. Da bekommen die "Ends" immer einen Hinweis, wozu sie gehören. Macht die Sache übersichtlicher.
Delete - Di 16.03.10 10:47
jasocul hat folgendes geschrieben : |
Ausnahmen:
- Strukturen die etwas länger oder verschachtelt sind. Da bekommen die "Ends" immer einen Hinweis, wozu sie gehören. Macht die Sache übersichtlicher.
|
das ist ein eindeutiges Zeichen, dafür dass du deinen Code überarbeiten solltest.
jaenicke - Di 16.03.10 10:54
Abgesehen davon gibts dafür ja die CnWizards. :mrgreen:
Bei (wie bereits von
Chemiker erwähnt) Assemblerquelltexten ist es aber auch noch eine Ausnahme, dass ich dort relativ ausführlich kommentiere. Und das sieht man ja auch in den VCL-Quelltexten, dass dort auch meist mehr kommentiert wird. Bei sowas sieht man sonst eben doch nicht so einfach durch.
Delete - Di 16.03.10 11:02
Assembler ist auch eine Ausnahme, da es da wohl unmöglich ist selbsterklärenden Code zu schreiben. ;)
zuma - Di 16.03.10 11:21
wenn man dann schon mehrzeiligen Kommentar schreibt, finde ich diese Variante
recht nervig, das gehört dann meiner Meinung nach so
zudem sind Kommentare immer davon abhängig, für wen man die schreibt:
als code, den man zum lernen gibt (z.b. für Azubi, Schüler, etc.) ist es besser, eher viel zu kommentieren, von ausgebildeten Programmierern kann man varlangen, das die auch (bei verwendung von sprechenden Bezeichnern) den Code ohne Kommentare lesen können und dann nur komplexe Logiken eines Kommentares bedürfen.
jasocul - Di 16.03.10 13:08
Luckie hat folgendes geschrieben : |
jasocul hat folgendes geschrieben : |
Ausnahmen:
- Strukturen die etwas länger oder verschachtelt sind. Da bekommen die "Ends" immer einen Hinweis, wozu sie gehören. Macht die Sache übersichtlicher.
|
das ist ein eindeutiges Zeichen, dafür dass du deinen Code überarbeiten solltest. |
Vergiss es. :mrgreen:
Ich weiß, dass es Programmierer gibt, die mehr als eine Bildschirmseite Code auf einmal geistig nicht verarbeiten können, aber zu denen gehöre ich nicht.
Delete - Di 16.03.10 13:53
Das hat nichts mit geistig verarbeiten zu tun, sondern mit Übersichtlichkeit, Verständlichkeit und Wartbarkeit.
jasocul - Di 16.03.10 14:25
Hatte die Ironie-Tags vergessen. :wink:
Natürlich bastel ich auch keinen Endlos-Code, aber man kann es in beide Richtungen übertreiben.
Ich meinte zum Beispiel eine Case-Struktur, die 20 Fälle hat und jeder Fall aus wenigen Zeilen Code besteht. Das wird nicht unübersichtlich, wenn es mal über 3 Bildschirmseiten geht. In solchen Fällen kommt hinter das "end" des "Case" ein Kommentar:
Da fange ich jedenfalls nicht an, für einen 5-zeiligen Fall eine Unter-Prozedur zu bauen.
---
Moderiert von
Narses: Beiträge zusammengefasst---
EDIT:
Ist eigentlich auch ein schlechtes Beispiel, da ich bisher noch keine Case-Struktur mit 20 Fällen hatte. Aber sobald das Case länger als eine Seite ist, schreibe ich den Kommentar dazu.
Nersgatt - Di 16.03.10 14:48
Ich finde, anhand dieser Diskussion ist sehr schön zu sehen, dass der Themenersteller die Quellcodekommentare so schreiben muss, wie es dem speziellen Lehrer gefällt. Die Note hängt dann davon ab, wie gut man den Geschmack des Lehrers trifft. :D
Wie zu kommentieren ist, ist zu großen Teilen Geschmackssache und kommt auch auf den Einzelfall an (z.B. für WEN der Kommentar gedacht ist).
Als wichtigstes ist aber zu sagen, dass man nicht die Funktion einzelner Befehle kommentieren soll, sondern man muss globaler denken. Die Funktion der Befehle kann ich nämlich mit F1 sehr schnell nachlesen, sofern ich sie nicht kenne.
Ich stimme übrigens jasocul zu. Ich mache auch manchmal Kommentare an die ENDs, wenn ich es für sinnvoll erachte. Man kann die Unterteilung in kleinere Prozeduren auch übertreiben. Man muss ein gesundes Maß finden.
Entwickler-Ecke.de based on phpBB
Copyright 2002 - 2011 by Tino Teuber, Copyright 2011 - 2025 by Christian Stelzmann Alle Rechte vorbehalten.
Alle Beiträge stammen von dritten Personen und dürfen geltendes Recht nicht verletzen.
Entwickler-Ecke und die zugehörigen Webseiten distanzieren sich ausdrücklich von Fremdinhalten jeglicher Art!