Autor Beitrag
sneki
Hält's aus hier
Beiträge: 8



BeitragVerfasst: Mo 15.03.10 12:05 
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:
ausblenden 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:
//Record, der sich eignet um nachher die Zutaten, sowie den Anzeigewert und den
//Namen des Rezepts in die das Array rmz zu laden
Rezept1 = record
    Name: string;
    Zutat1: string;
    Zutat2: string;
    Zutat3: string;
    Zutat4: string;
    Anzwert: Integer;
  end;

//Record der für ran verwendet wird sich zur Speicherung eines Rezeptnamens
//und des Pfades zur Backanleitung eignet
Rezept2 = record
    Name: string;
    Anleitung: string;
  end;

//Konstanten zur Auswertung der Auswahl des Benutzers
const
  Kirsche='Kirsche';
  Kokos='Kokos';
  Nuss='Nuss';
  Schoko='Schokolade';


ausblenden 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:
//Überprüfung ob Checkbox1 (Kirschen) gewählt ist
if Checkbox1.Checked=true then
begin
  for i:=1 to 20 do
  //Überprüfung ob Anzeigewert 0 ist
    begin if rmz[i].Anzwert=0 then
    //Wenn 0, dann Vergleich ob Zutat1 der Rezepte in rmz-Variablen mit Auswahl
    //übereinstimmt
      begin if rmz[i].Zutat1=Kirsche
            then begin
                for k:=1 to 20 do
                  //Wenn Rezept rmz[i] Kirschen enthält: Vergleich des
                  //Rezeptnamen mit dem der ran-Variablen
                  begin if rmz[i].Name = ran[k].Name then
                  //Anzeige des Rezeptnamen aus ran[k] in der Listbox
                      Listbox1.Items.Add(ran[k].Name )
                  end;
                  //Da Rezept nun in der Liste ist: Anzeigewert wird 1
              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
ontopic starontopic starontopic starontopic starontopic starontopic starofftopic starofftopic star
Beiträge: 8548
Erhaltene Danke: 477

Windows 7, Windows 10
D7 PE, Delphi XE3 Prof, Delphi 10.3 CE
BeitragVerfasst: 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:
ausblenden Delphi-Quelltext
1:
2:
3:
4:
5:
6:
7:
8:
9:
10:
11:
if Checkbox1.Checked then // nie auf = true oder so vergleichen, das kann schonmal schief gehen!
begin
  for i:=1 to 20 do
  begin 
      if rmz[i].Anzwert=0 then
      //Wenn 0, dann Vergleich ob Zutat1 der Rezepte in rmz-Variablen mit Auswahl
      //übereinstimmt
      begin 
          if rmz[i].Zutat1=Kirsche then 
          begin
              ...

_________________
We are, we were and will not be.
jaenicke
ontopic starontopic starontopic starontopic starontopic starontopic starontopic starofftopic star
Beiträge: 19315
Erhaltene Danke: 1747

W11 x64 (Chrome, Edge)
Delphi 11 Pro, Oxygene, C# (VS 2022), JS/HTML, Java (NB), PHP, Lazarus
BeitragVerfasst: 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 user profile iconGausi 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:
ausblenden 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:
ausblenden 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.
Luckie
Ehemaliges Mitglied
Erhaltene Danke: 1



BeitragVerfasst: Mo 15.03.10 13:10 
Benennen die Variablen und Steuerelemente gescheit.
ausblenden 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.

ausblenden Delphi-Quelltext
1:
2:
//Überprüfung ob Anzeigewert 0 ist
    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:
ausblenden Delphi-Quelltext
1:
if (winmajorver = 5and (winminorver = 1then					

So was müsste ich kommentieren, dass ich da uaf Windowx XP prüfe. Deswegen:
ausblenden Delphi-Quelltext
1:
2:
3:
4:
function IsWindowsXP: Boolean;
begin
  Result := (winmajorver = 5and (winminorver = 1);
end;

Und dann:
ausblenden Delphi-Quelltext
1:
If IsWindowsXP then					

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: www.michael-puff.de/...ikel/CleanCode.shtml
dummzeuch
ontopic starontopic starontopic starontopic starontopic starontopic starhalf ontopic starofftopic star
Beiträge: 593
Erhaltene Danke: 5


Delphi 5 ent, Delphi 6 bis Delphi XE8 pro
BeitragVerfasst: Mo 15.03.10 23:16 
user profile iconGausi hat folgendes geschrieben Zum zitierten Posting springen:

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 ...

ausblenden Delphi-Quelltext
1:
2:
// auf Null pruefen
if Variable=0 then


... schreibt, der gehoert dafuer geschlagen. Wer als Chef oder QM-Fuzzi Kommentare wie ...

ausblenden Delphi-Quelltext
1:
2:
3:
4:
5:
// Prozedur Trallala
// von: <Autor>
// geschrieben: <datum>
// ... tausende weitere sinnlose Angaben
procedure Trallala;


... verlangt, hat zuviele schlechte Buecher gelesen.

So, und jetzt leg' ich mich wieder hin....

twm
Martok
ontopic starontopic starontopic starontopic starontopic starontopic starofftopic starofftopic star
Beiträge: 3661
Erhaltene Danke: 604

Win 8.1, Win 10 x64
Pascal: Lazarus Snapshot, Delphi 7,2007; PHP, JS: WebStorm
BeitragVerfasst: 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 user profile iconLuckie und user profile icondummzeuch vollumfänglich Recht.

user profile icondummzeuch hat folgendes geschrieben Zum zitierten Posting springen:
Wer als Chef oder QM-Fuzzi Kommentare wie ...

ausblenden Delphi-Quelltext
1:
2:
3:
4:
5:
// Prozedur Trallala
// von: <Autor>
// geschrieben: <datum>
// ... tausende weitere sinnlose Angaben
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.

_________________
"The phoenix's price isn't inevitable. It's not part of some deep balance built into the universe. It's just the parts of the game where you haven't figured out yet how to cheat."
Chemiker
ontopic starontopic starontopic starontopic starontopic starontopic starontopic starofftopic star
Beiträge: 194
Erhaltene Danke: 14

XP, Vista 32 Bit, Vista 64 Bit, Win 7 64 Bit
D7, BDS 2006, RAD Studio 2009+C++, Delphi XE2, XE3, VS 2010 Prof.
BeitragVerfasst: 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
ontopic starontopic starontopic starontopic starontopic starontopic starhalf ontopic starofftopic star
Beiträge: 6393
Erhaltene Danke: 147

Windows 7 + Windows 10
Sydney Prof + CE
BeitragVerfasst: 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.
Luckie
Ehemaliges Mitglied
Erhaltene Danke: 1



BeitragVerfasst: Di 16.03.10 10:47 
user profile iconjasocul hat folgendes geschrieben Zum zitierten Posting springen:

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
ontopic starontopic starontopic starontopic starontopic starontopic starontopic starofftopic star
Beiträge: 19315
Erhaltene Danke: 1747

W11 x64 (Chrome, Edge)
Delphi 11 Pro, Oxygene, C# (VS 2022), JS/HTML, Java (NB), PHP, Lazarus
BeitragVerfasst: Di 16.03.10 10:54 
Abgesehen davon gibts dafür ja die CnWizards. :mrgreen:

Bei (wie bereits von user profile iconChemiker 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.
Luckie
Ehemaliges Mitglied
Erhaltene Danke: 1



BeitragVerfasst: Di 16.03.10 11:02 
Assembler ist auch eine Ausnahme, da es da wohl unmöglich ist selbsterklärenden Code zu schreiben. ;)
zuma
ontopic starontopic starontopic starontopic starontopic starontopic starofftopic starofftopic star
Beiträge: 660
Erhaltene Danke: 21

Win XP, Win7, Win 8
D7 Enterprise, Delphi XE, Interbase (5 - XE)
BeitragVerfasst: Di 16.03.10 11:21 
wenn man dann schon mehrzeiligen Kommentar schreibt, finde ich diese Variante
ausblenden Delphi-Quelltext
1:
2:
3:
// blabla
// blubbblubb
// blabla

recht nervig, das gehört dann meiner Meinung nach so
ausblenden Delphi-Quelltext
1:
2:
3:
4:
5:

  blabla
  blubbblubb
  blabla
}


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.

_________________
Ich habe nichts gegen Fremde. Aber diese Fremden sind nicht von hier! (Methusalix)
Warum sich Sorgen ums Leben machen? Keiner überlebts!
jasocul
ontopic starontopic starontopic starontopic starontopic starontopic starhalf ontopic starofftopic star
Beiträge: 6393
Erhaltene Danke: 147

Windows 7 + Windows 10
Sydney Prof + CE
BeitragVerfasst: Di 16.03.10 13:08 
user profile iconLuckie hat folgendes geschrieben Zum zitierten Posting springen:
user profile iconjasocul hat folgendes geschrieben Zum zitierten Posting springen:

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.
Luckie
Ehemaliges Mitglied
Erhaltene Danke: 1



BeitragVerfasst: Di 16.03.10 13:53 
Das hat nichts mit geistig verarbeiten zu tun, sondern mit Übersichtlichkeit, Verständlichkeit und Wartbarkeit.
jasocul
ontopic starontopic starontopic starontopic starontopic starontopic starhalf ontopic starofftopic star
Beiträge: 6393
Erhaltene Danke: 147

Windows 7 + Windows 10
Sydney Prof + CE
BeitragVerfasst: 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:
ausblenden Delphi-Quelltext
1:
end//case					

Da fange ich jedenfalls nicht an, für einen 5-zeiligen Fall eine Unter-Prozedur zu bauen.

---Moderiert von user profile iconNarses: 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
ontopic starontopic starontopic starontopic starontopic starontopic starhalf ontopic starofftopic star
Beiträge: 1581
Erhaltene Danke: 279


Delphi 10 Seattle Prof.
BeitragVerfasst: 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.

_________________
Gruß, Jens
Zuerst ignorieren sie dich, dann lachen sie über dich, dann bekämpfen sie dich und dann gewinnst du. (Mahatma Gandhi)