3. Wie schreibt man Kommentare "schön"

Wie schreibt man Kommentare "schön"

  • T

    volkard schrieb:

    DEvent schrieb:

    if ( tank.getLiter() + tank.getKapazität() < liter )

    die zeile hab ich nicht kapiert. würde hier ein kommentar helfen?

    Nein! Lern einfach rechnen :p

    0
  • C

    DEvent schrieb:

    if ( tank.getLiter() + tank.getKapazität() < liter )

    Jetzt muß man nur noch wissen, was genau getKapazität() und getLiter() zurückgeben (bei getLiter() würde ich die aktuelle Füllmenge vermuten, bei getKapazität() entweder die Maximale Füllmenge oder die maximal mögliche Zufüllung - in jedem Fall müsstest du erklären, warum du gerade die Summe von beidem mit der Tankmenge vergleichen willst).

    btw, soll die Funktion Benzin auffüllen, bis der Tank voll ist? oder soll sie genau/maximal 'liter' Liter Benzin auffüllen?

    0
  • D

    volkard schrieb:

    DEvent schrieb:

    if ( tank.getLiter() + tank.getKapazität() < liter )

    die zeile hab ich nicht kapiert. würde hier ein kommentar helfen?

    Wie gesagt, wenn man den Code nicht gleich kapiert muss ein Kommentar hin. Ich wollte nur testen ob ihr das verstanden habt.

    0
  • ?

    da muss kein kommentar hin. der code muss refaktorisiert werden

    0
  • T
     

    if ( tank.getKapazität() - tank.getLiter() > liter )

    Macht irgendwie mehr Sinn oder?

    CStoll schrieb:

    Jetzt muß man nur noch wissen, was genau getKapazität() und getLiter() zurückgeben (bei getLiter() würde ich die aktuelle Füllmenge vermuten, bei getKapazität() entweder die Maximale Füllmenge oder die maximal mögliche Zufüllung - in jedem Fall müsstest du erklären, warum du gerade die Summe von beidem mit der Tankmenge vergleichen willst)

    Gehört IMO in die Klassenschnittstelle oder -Doku, nicht mitten in den Code.

    CStoll schrieb:

    btw, soll die Funktion Benzin auffüllen, bis der Tank voll ist? oder soll sie genau/maximal 'liter' Liter Benzin auffüllen?

    public void betanke(double liter)

    Ist doch selbsterklärend: Betanke Auto mit 'liter' Litern (überlaufschutz ist integriert, wie bei allen modernen Autos)
    Eine weitere Methode könnte sein

    public void volltanken()
    0
  • C

    THX 1138 schrieb:

    if ( tank.getKapazität() - tank.getLiter() > liter )

    Macht irgendwie mehr Sinn oder?

    CStoll schrieb:

    Jetzt muß man nur noch wissen, was genau getKapazität() und getLiter() zurückgeben (bei getLiter() würde ich die aktuelle Füllmenge vermuten, bei getKapazität() entweder die Maximale Füllmenge oder die maximal mögliche Zufüllung - in jedem Fall müsstest du erklären, warum du gerade die Summe von beidem mit der Tankmenge vergleichen willst)

    Gehört IMO in die Klassenschnittstelle oder -Doku, nicht mitten in den Code.

    OK, wo die Erklärung steht, ist mir eigentlich egal - jedenfalls sollte ich sie finden können.

    CStoll schrieb:

    btw, soll die Funktion Benzin auffüllen, bis der Tank voll ist? oder soll sie genau/maximal 'liter' Liter Benzin auffüllen?

    public void betanke(double liter)

    Ist doch selbsterklärend: Betanke Auto mit 'liter' Litern (überlaufschutz ist integriert, wie bei allen modernen Autos)

    Ja, vom Namen her wäre ich auch soweit gekommen, aber das "while ( !tank.istVoll() ) tank.betanke(liter);" hat mich etwas verwirrt.

    0
  • F

    THX 1138 schrieb:

    CStoll schrieb:

    btw, soll die Funktion Benzin auffüllen, bis der Tank voll ist? oder soll sie genau/maximal 'liter' Liter Benzin auffüllen?

    public void betanke(double liter)

    Ist doch selbsterklärend: Betanke Auto mit 'liter' Litern (überlaufschutz ist integriert, wie bei allen modernen Autos)
    Eine weitere Methode könnte sein

    public void volltanken()

    Sicher? Betanke mit liter Litern hört sich klar wahrscheinlicher an, der Code sieht aber eher nach "betanke auf Füllstand von liter Liter" aus.

    Und im umgekehrten Fall ist dein Überlaufschutz kaputt, oder wenigstens suboptimal oder ggf. auch einfach irreführend benannt: du willst 10l tanken, hast noch 5l Restkapazität und bekommst gar nichts in den Tank.

    0
  • T

    🙄

    Es ist doch nur ein Beispiel, wie man Code schreibt, der selbsterklärend ist.
    Ob das Beispiel jetzt stimmt oder nicht..Optimierung einer Tankbefüllungsroutine ist hier irgendwie OT

    0
  • J

    DEvent schrieb:

    Wie gesagt, wenn man den Code nicht gleich kapiert muss ein Kommentar hin. Ich wollte nur testen ob ihr das verstanden habt.

    Wir werden das erst verstehen wenn Du verstanden hast, daß "man versteht's nicht" kein ausreichender Grund für nen Kommentar ist. Code aufräumen und schöner strukturieren. Warum nicht einfach die Abfrage in ne schön benannte Funktion stecken?

    0
  • D

    THX 1138 schrieb:

    🙄

    Es ist doch nur ein Beispiel, wie man Code schreibt, der selbsterklärend ist.
    Ob das Beispiel jetzt stimmt oder nicht..Optimierung einer Tankbefüllungsroutine ist hier irgendwie OT

    Doch das ist jetzt das neue Thema für den Thread:

    1. Optimierung einer Tankbefüllungsroutine
    1a. Suchen von optimalen Namen für eine Tankbefüllungsroutine
    2. Kommentardiskussion über die Tankbefüllungsroutine
    2a. Diskussion in wie fern Kommentare nötig sind über die Tankbefüllungsroutine
    2b. Vorschläge für Kommentar über die Tankbefüllungsroutine
    3. Implementation der Tankbefüllungsroutine in C++
    4. Testen der Tankbefüllungsroutine
    4a. Alpha Test der Tankbefüllungsroutine
    4b. Beta Test der Tankbefüllungsroutine
    4c. Bugs der Tankbefüllungsroutine beheben und erneutes Testen der Tankbefüllungsroutine
    5. Margeting der Tankbefüllungsroutine
    5a. Diskussion in wie fern eine Tankbefüllungsroutine für jedes Auto nötig seih
    5b. Beauftragen einer Vermaktungsfirma für die Tankbefüllungsroutine
    6. Auslieferung der Tankbefüllungsroutine
    7. Support für die Tankbefüllungsroutine

    Ach Leuz nehmt doch nicht alles Todernst 🙂

    Wenn Bezeichner selbsterklärend sind, wie sie es normalerweise sein sollten, da wir in Zeiten von Unicode und Bezeichner > 8 Zeichen leben, dann sind Kommentare überflüssig. Ebenso sind Kommentare überflüssig wenn der Code selbsterklärend ist.
    Ich erwarte von jedem der meinen Code liest, das er die Sprache auch kennt. Wenn ich allerdings Hacks benutze um Geschwindigkeit rauszuholen, dann muss ich diese Hacks erklären.

    daß "man versteht's nicht" kein ausreichender Grund für nen Kommentar ist.

    Klar ist das ein ausreichender Grund. Wozu brauchst du sonst Kommentare?
    Bei einer Methode wie "String toString()" brauchst du keine Kommentare. Auch nicht bei "double rechne2tePotenz(double x)" oder bei "double rechnePotenz(double basis, double potenz)".

    0
  • D

    THX 1138 schrieb:

    if ( tank.getKapazität() - tank.getLiter() > liter )

    Macht irgendwie mehr Sinn oder?

    CStoll schrieb:

    Jetzt muß man nur noch wissen, was genau getKapazität() und getLiter() zurückgeben (bei getLiter() würde ich die aktuelle Füllmenge vermuten, bei getKapazität() entweder die Maximale Füllmenge oder die maximal mögliche Zufüllung - in jedem Fall müsstest du erklären, warum du gerade die Summe von beidem mit der Tankmenge vergleichen willst)

    Gehört IMO in die Klassenschnittstelle oder -Doku, nicht mitten in den Code.

    CStoll schrieb:

    btw, soll die Funktion Benzin auffüllen, bis der Tank voll ist? oder soll sie genau/maximal 'liter' Liter Benzin auffüllen?

    public void betanke(double liter)

    Ist doch selbsterklärend: Betanke Auto mit 'liter' Litern (überlaufschutz ist integriert, wie bei allen modernen Autos)
    Eine weitere Methode könnte sein

    public void volltanken()

    Ja ich hab eigentlich sowas gemeint, hab ein wenig zu schnell gepostet.

    0
  • T

    Ist aber ein gutes Beispiel für "schöne" Namen und jeder Kommentar ist überflüssig.
    Ich muss nicht scrollen oder in eine andere Datei schauen um zu verstehn, was passiert...und das ist gut so 🙂

    0
  • J

    DEvent schrieb:

    Klar ist das ein ausreichender Grund. Wozu brauchst du sonst Kommentare?

    Nein, es ist ein Grund den Code so umzuschreiben, daß man ihn eben doch versteht. Deine Beispiele zeigen doch deutlich, daß man das tun sollte. Warum bestehst Du also auf Kommentare?

    0
  • ?

    Beim Kommentieren gilt dasselbe wie bei vielen anderen Sachen auch:
    Soviel wie nötig, sowenig wie möglich.

    Was gutes Kommentieren (wert) ist, lernt man am besten, imdem man beauftragt wird, fremder Leute Programme zu debuggen, gerne auch in Programmiersprachen, deren Spezi sich inzwischen geändert hat. 🙂

    Tschau

    0
  • F

    THX 1138 schrieb:

    🙄

    Es ist doch nur ein Beispiel, wie man Code schreibt, der selbsterklärend ist.
    Ob das Beispiel jetzt stimmt oder nicht..Optimierung einer Tankbefüllungsroutine ist hier irgendwie OT

    Ja ja, Hauptsache mal ein "🙄" in die Runde geworfen. Wenn du auch nur einen halben Augenblick lang nachgedacht hättest dann wär dir vielleicht klar geworden dass es genau darum ging dass der Code eben nicht selbsterklärend ist.

    0
  • F

    DEvent schrieb:

    Doch das ist jetzt das neue Thema für den Thread:

    1. Optimierung einer Tankbefüllungsroutine
    1a. Suchen von optimalen Namen für eine Tankbefüllungsroutine
    2. Kommentardiskussion über die Tankbefüllungsroutine
    2a. Diskussion in wie fern Kommentare nötig sind über die Tankbefüllungsroutine
    2b. Vorschläge für Kommentar über die Tankbefüllungsroutine
    3. Implementation der Tankbefüllungsroutine in C++
    4. Testen der Tankbefüllungsroutine
    4a. Alpha Test der Tankbefüllungsroutine
    4b. Beta Test der Tankbefüllungsroutine
    4c. Bugs der Tankbefüllungsroutine beheben und erneutes Testen der Tankbefüllungsroutine
    5. Margeting der Tankbefüllungsroutine
    5a. Diskussion in wie fern eine Tankbefüllungsroutine für jedes Auto nötig seih
    5b. Beauftragen einer Vermaktungsfirma für die Tankbefüllungsroutine
    6. Auslieferung der Tankbefüllungsroutine
    7. Support für die Tankbefüllungsroutine

    Wenn du dir Threadtitel & OP anschaust wirst du feststellen dass es in der Tat um Punkt 2 deiner Liste geht, und wenigstens der ein oder andere glaubt dass 1a in direktem Zusammenhang damit steht.

    Aber durchaus sehr witzig dein Post, wäre er nicht fehl am Platz 🙂

    0
  • ?

    Wird eigentlich Diesel oder Benzin getankt? :p

    0
  • T

    finix schrieb:

    ...dass es genau darum ging dass der Code eben nicht selbsterklärend ist.

    Ist er eben doch. Lässt sich lesen wie ein deutscher Text. Keine weiteren Fragen, ihr Zeuge..
    Und weil du auf Fehlern im Code rumhacktest, sagte ich, es ist nur ein (ungetestetes) Beispiel, aber ich hab trotzdem verstanden was er meint, Du offensichtlich nicht.

    TactX schrieb:

    Wird eigentlich Diesel oder Benzin getankt? :p

    ..durchaus sehr witzig dein Post, wäre er nicht fehl am Platz 🙂

    0
  • C

    THX 1138 schrieb:

    finix schrieb:

    ...dass es genau darum ging dass der Code eben nicht selbsterklärend ist.

    Ist er eben doch. Lässt sich lesen wie ein deutscher Text. Keine weiteren Fragen, ihr Zeuge..

    Wie schon gesagt - wenn dir klar ist, was genau die verwendeten Funktionen machen, ist der Code klar verständlich. WENN...

    Allerdings geht das auch nicht immer aus dem Namen der Methoden hervor (das sieht man schon bei deinem Beispiel - bei getKapazität() müsste ich nachschauen, was die bei dir machen soll, genauso geht die Semantik der betanke()-Methode aus dem Quellcode nicht unbedingt hervor*) und da braucht man dann halt einen kurzen Kommentar, der diese Feinheiten erklärt.
    (wobei, ich würde solche Erklärungen vermutlich zur Methodendeklaration packen - am besten im DoxyGen-Stil, um am Ende eine vernünftige Dokumentation für die Anwender anlegen zu können)

    PS: Wer ein Programm geschrieben hat, weiß meistens, was (und warum) es macht. Wer ein fremdes Programm liest, dürfte sich trotzdem über ein paar Kommentare freuen 😉

    * aber das auch daran liegen, daß die Methode "nur ein (ungetestetes) Beispiel" ist 😉

    0
  • T

    Wegen dem Problem ob man betankt mit oder betankt bis Liter:
    Im Lab-Jargon gibts ganz einfach verschiedene Ausdrücke dafür
    "add 20mL H2O" heisst: gebe 20mL Wasser dazu
    "ad 20mL H2O+ heisst: fülle auf 20mL auf ("ad" kommt glaub ich ausm Latein)

    Für meinen Geschmack gehört Beschreibung der Methode einfach in die Doku, oder wenn im Source, dann halt über dem Funktionskopf ne kurze Beschreibung (am besten Doxygen Style, das ist wahr). Diese Einzeiler mitten drin mag ich nicht, stören bei mir den Lesefluss.

    0
Anmelden zum Antworten