Wie schreibt man Kommentare "schön"

Jester

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?

DEvent

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

DEvent

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.

THX 1138

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

Jester

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?

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

finix

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.

finix

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

Wird eigentlich Diesel oder Benzin getankt? :p

THX 1138

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

CStoll

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

THX 1138

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.

finix

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

Ja, alles simple, gebräuchliche, sehr verständliche deutsche Worte. Nur, was bedeuten sie im Kontext?

volkard

CStoll schrieb:

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,

ich nicht. ich kenne das wort kapazität nämlich. die funktion ist fein benamst. aber getLiter ist schlimm.
außerdem sieht man, daß der code suboptimal war daran, daß der fehler in der berechnung sich über so viele postings verstecken konnte, obwohl ich mit dem finger draufgezeigt hatte. aber trotzdem war er viel besser als durchschnittlicher code.

und irgendwie erinnert mich das an diese selbstüberlistung (mit sehr schattigem kommentar):

class Konto{
   unsigned int stand;
   ...
   bool abheben(unsigned int betrag){
      if(stand-betrag>=0){//wenn genug geld auf dem konto ist, also 
         //nach dem abheben noch was drauf wäre
         doAbheben(betrag);
         return true;
      }
      return false;
   }
};
//zusatzfrage: was ist daran falsch?

volkard

THX 1138 schrieb:

("ad" kommt glaub ich ausm Latein)

und heißt wohl "bis".

THX 1138 schrieb:

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

nö. einfach betankeBis(double neuFuellstand) oder betanke(double hinzufuegMenge). übernimm doch einfach die tricks, die im labor auch funktionieren.

THX 1138

volkard schrieb:

THX 1138 schrieb:

("ad" kommt glaub ich ausm Latein)

und heißt wohl "bis".

Hab mein bisschen Latein halt aus Asterix

volkard schrieb:

nö. einfach betankeBis(double neuFuellstand) oder betanke(double hinzufuegMenge). übernimm doch einfach die tricks, die im labor auch funktionieren.

Tu ich auch, war ja nicht mein Code. Aber grade auch in der STL findet man viele Namen, die nicht eindeutig sind. zB empty() Leert das nun den Container oder wie? Müsste is_empty heissen. Da bin ich dann froh über ne Doku, aber Du hast recht, da nützen auch Kommentare im Code nichts, wer kämpft sich schon durch die den Header von vector.

doAbheben(betrag);

Babylonische Sprachverwirrung? Warum nicht tueRetireMoney(valor)?

volkard

TactX schrieb:

Wird eigentlich Diesel oder Benzin getankt? :p

um die schnittstelle nicht zu ändern, wird der double liter überladen und positive mengen bedeuten Benzin und negative bedeuten Diesel. Bald danach würd nochmal überladen und kommazahlen mit führender 0 bedeuten wenn positiv, dann der kehrwert in Wasserstoff und wenn negativ dann den kehrwert in Erdgas. das reicht natürlich noch nicht. ist aber für uns kein problem. die fünfte überladung ist gleich allgemeiner. wenn man 0 übegibt, muss man tanken umittelbar danach noch zweimal aufrufen, zuerst mit einer positiven ganzen zahl, die den stofftyp besimmt und danach mit einer zahl, die die menge bestimmt, wobei negative mengen als ad und positive als add zählen. will man aber eh nur add verwenden, kann man auch dem stofftyp einen nachkommaanteil dranhängen, dessen kehrwert dann als zu tankende menge interpretiert wird und man spart sich den dritten aufruf. mit negativem stofftyp und nachkommateil wird entsprechend ad verwendet. es geht halt nichts über flexible schnittstellen. gleich wird noch die version mit dem ersten aufruf !=0 als obsolet erklärt und gefordert, daß in 5 jahren keiner mehr sie verwendet. die nachfolgeversion für einen parameter wird sich dann der einfachheit halber auf die kettenbruchzerlegung der übergebeben zahl stützen mit später noch näher zu definierender bedeutung. ok, die schnittstelle muss kommentiert werden. manchmal geht's halt nicht anders. aber dann wenigstens gut kommentiert. wichtigste regel: ein klarer kommentar darf keine verben enthalten, damit keine redundanz vorkommt. außerdem darf er nicht das offensichtlicher erklären, wie den unterschied von add und ad. und er muß für doxygen lesbar sein.

net 0

Jester schrieb:

...es ist ein Grund den Code so umzuschreiben, daß man ihn eben doch versteht. Deine Beispiele zeigen doch deutlich, daß man das tun sollte.

das geht leider nicht immer...

DEvent

Jester schrieb:

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?

Hab doch gesagt, wenn man so ober coole Hacks benutzt, wie Bitshiften nach rechts/links oder oben/unten, oder wenn man Bitausrichtung benutzt oder wenn es Spezialfälle gibt, Ausnahmen eben. Vielleicht gibt es Seiteneffekte, die nicht sofort ersichtlich sind.

Die Sprachen (C++, C#, Java, Ruby, ...) sind nicht umsonst natürlichen Sprachen ähnlich. Im Idealfall kann man den Code wie einen normalen Satzt lesen.

Wenn man aber C++ immernoch wie Asm coded...

volkard

hab gerade beim ausgraben von code für http://www.c-plusplus.net/forum/viewtopic.php?p=1158033#1158033 zufällig einen vielzeilenkommentar in meinem code gefunden.

typedef __int64 TimeDiff;

class Time:public Count
{//Simulationszeit in Picosekunden
private:
public:
	TimeDiff data;//2^64 Picosekunden sind ca. 1/2 Jahr
public:
	Time(void)
	{
		data=0;
	};
	bool operator<(Time b) const
	{
		//Mit 'return data<b.data' geht es nicht, weil beim 
		//Überlauf falsche Ergebnisse erscheinen. Wenn man aber 
		//zuerst 'b.data-data' berechnet(auch mit Überlauf), dann 
		//ist das Ergebnis immer korrekt, solange der Zeitraum 
		//noch unter 2^64*0.5 bleibt. Es dürfen in der Simulation 
		//also die Timer auf bis zu 1/4 Jahr aufgezogen werden. 
		return b.data-data>0;
	};
	Time operator+(TimeDiff i)
	{
		Time result;
		result.data=data+i;
		return result;
	};
	Time operator-(TimeDiff i)
	{
		Time result;
		result.data=data-i;
		return result;
	};
	TimeDiff operator-(Time t)
	{
		return data-t.data;
	};
	friend ostream &operator<<(ostream &out,Time t);
};
const TimeDiff PICOSEKUNDE=1;
const TimeDiff NANOSEKUNDE=1000*PICOSEKUNDE;
const TimeDiff MIKROSEKUNDE=1000*NANOSEKUNDE;
const TimeDiff MILLISEKUNDE=1000*MIKROSEKUNDE;
const TimeDiff SEKUNDE=1000*MILLISEKUNDE;
const TimeDiff MINUTE=60*SEKUNDE;
const TimeDiff STUNDE=60*MINUTE;
const TimeDiff TAG=24*STUNDE;

das war ein timer für einen netzwerksimulator. nanosekunden waren nicht genug, weil ein einer nanosekunde das signal auf dem kabel 20 centimeter macht -> es wäre zu ruckelig; der schüler könnte den zeitraffer nicht weit genug aufziehen, um das signal auf dem kaben zu sehen.

Wie schreibt man Kommentare &quot;schön&quot;

Wie schreibt man Kommentare "schön"