Wie schreibt man Kommentare "schön"
-
Blue-Tiger schrieb:
Wenn du den Unterschied nicht kennst dann schlag ihn halt nach
http://de.wikipedia.org/wiki/Strategie#Abgrenzungdas habe ich natürlich, und da steht: "Strategie und Taktik hängen eng mit einander zusammen:". der untersched ist kaum mehr als marginal, und dinge unterscheiden zu wollen, indem man ihnen begrifflich stark verwandte namen gibt ist zumindest ungeschickt und gerade für jemanden, der "styleguides" schreibt, kein gutes aushängeschild.
"
"
-
Ich persönlich finde folgenden Style eigentlich ganz schön, wobei ich mir den auch irgendwo abgeschaut habe (ich glaube sogar von jmd. hier aus dem Forum, aber weiß nicht mehr genau):
//****************************************************************************** //* //* myClass.hpp //* //* (c) by Author <info@domain.de> //* //****************************************************************************** class myClass { public: myClass(); virtual ~myClass(); void doSomething(); void doSomethingElse(); private: int m_Counter; };#include "myClass.hpp" myClass::myClass() : m_Counter(0) { } myClass::~myClass() { } //****************************************************************************** //* //* Irgendwelche Erklärungen zur Funktion, falls notwendig oder erwünscht //* //****************************************************************************** void myClass::doSomething() { // zuerst das machen, weil ... // als nächstes das, weil ... } //****************************************************************************** //* //* Irgendwelche Erklärungen zur Funktion, falls notwendig oder erwünscht //* //****************************************************************************** void myClass::doSomethingElse() { m_Counter++; }Vorteil dieser Variante ist, dass man mit einem Multiline-Kommentar mal ebend ganze Codestellen auskommentieren kann. Wenn man zwischendrin Multiline-Kommentare verwendet, dann kann das schon schwieriger werden. Außerdem bin ich ein Freund davon, dass jede Funktion (Methode) im Code sichtbar getrennt von den anderen ist, was man durch die zeilenlangen * meiner Meinung nach ganz gut erreicht.
Wie gesagt, es ist subjektiv, aber bisher habe ich noch nichts gefunden, was mir besser gefällt, wenn jmd. Vorschläge hat, bin ich wie immer offen.
-
mantiz schrieb:
Vorteil dieser Variante ist, dass man mit einem Multiline-Kommentar mal ebend ganze Codestellen auskommentieren kann. Wenn man zwischendrin Multiline-Kommentare verwendet, dann kann das schon schwieriger werden.
Ganze Codeblöcke sollte man eigentlich in jedem Code-Editor auch mit der //-Variante einfach auskommentieren können.
Ansonsten gibts auch noch #if 0 was bei großen Blöcken eh schöner ist.Außerdem bin ich ein Freund davon, dass jede Funktion (Methode) im Code sichtbar getrennt von den anderen ist, was man durch die zeilenlangen * meiner Meinung nach ganz gut erreicht.
ich finde sowas immer nur nervig weil man mehr scrollen muss und weniger code auf den bildschirm passt.
Funktionen kommentiere ich (wenn) so:
void foo() // dies und das { }
-
MisterX schrieb:
Ist es sinvoller diese hinter die Codezeile zu schreiben oder darüber oder darunter, oder je nach Bedarf eine Möglichkeit auswählen
(z.B dahinter, wenn der Code kurz ist und ansonsten darüber)?nach bedarf wählen.
-
Wenn ihr glaubt, einen Kommentar zu benötigen, refaktorisiert den Code, so das jeder Kommentar überflüssig wird.
-
wisser schrieb:
Wenn ihr glaubt, einen Kommentar zu benötigen, refaktorisiert den Code, so das jeder Kommentar überflüssig wird.
Unterscheidest Du zwischen "Kommentaren" innerhalb von Methoden und "Dokumentationen", die zum Beispiel direkt oberhalb der Methoden stehen?
-
dfk... schrieb:
Blue-Tiger schrieb:
Wenn du den Unterschied nicht kennst dann schlag ihn halt nach
http://de.wikipedia.org/wiki/Strategie#Abgrenzungdas habe ich natürlich, und da steht: "Strategie und Taktik hängen eng mit einander zusammen:". der untersched ist kaum mehr als marginal, und dinge unterscheiden zu wollen, indem man ihnen begrifflich stark verwandte namen gibt ist zumindest ungeschickt und gerade für jemanden, der "styleguides" schreibt, kein gutes aushängeschild.
"
"Die Begriffe sind verwandt, das stimmt. Allerdings unterscheiden sie sich eindeutig. Nimm zum Beispiel das Militär: Die strategische Führung gibt Anweisungen heraus, die der Erfüllung des Gesamtauftrages dienen. Also beispielsweise: "Ort A erobern" oder "Fabrik B zerstören".
Auf den taktischen Ebenen wird dann die Erfüllung dieser Unterziele geplant (also beispielsweise: "Einheit A geht über Strasse Z in Ort B vor, Einheit D über Strasse Y in Ort C. Damit ist der Weg für Einheit E gesichert, die in Ort A vorgeht."
Letztlich ist eine Strategie also einer Taktik übergeordnet. Und damit ist auch die Benennung der Kommentare "sinnig". Strategische Kommentare beschreiben das Ziel/Interface einer Klasse/Datei, taktische Kommentare die jeweilige Implementierung.
-
wisser schrieb:
Wenn ihr glaubt, einen Kommentar zu benötigen, refaktorisiert den Code, so das jeder Kommentar überflüssig wird.
Ach ja? Helf mir mal aus, was soll ich hier tun:
/** * <API Docs> */ void foo( bar const& b ) { // using algorithm x to accomplish foo // Rationale: bla bla blurb, etc lots of; code goes(here); // following line [does Y|is equivalent to code Z] some var = highly * optimised (obfuscated) % computation; }
-
finix schrieb:
wisser schrieb:
Wenn ihr glaubt, einen Kommentar zu benötigen, refaktorisiert den Code, so das jeder Kommentar überflüssig wird.
Ach ja? Helf mir mal aus, was soll ich hier tun:
/** * <API Docs> */ void foo( bar const& b ) { // using algorithm x to accomplish foo // Rationale: bla bla blurb, etc lots of; code goes(here); // following line [does Y|is equivalent to code Z] some var = highly * optimised (obfuscated) % computation; }man kann an beispielen mit foo und bar nicht razusfinden, was hübsche kommentare sind.
da ich mir aussuchen kann, was fuu und blubs bedeuten, hier die stark verbesserte version:
void blaBlaBlurbByX( bar const& b ) { lots of; code goes(here); some var = Y/Z(...); }
-
Sid2K6 schrieb:
Die Begriffe sind verwandt, das stimmt. Allerdings unterscheiden sie sich eindeutig. Nimm zum Beispiel das Militär: Die strategische Führung gibt Anweisungen heraus, die der Erfüllung des Gesamtauftrages dienen. Also beispielsweise: "Ort A erobern" oder "Fabrik B zerstören".
auch das ist unfug. des einen strategie ist des anderen taktik.
-
@mantiz
dein Kommentar-Stil ist optisch viel zu sehr ablenkend und verbraucht viel zu viel Platz. Du verbringst ja mehr Zeit mit den Kommentaren, als mit dem Code (sowohl r, als auch w).volkard schrieb:
Sid2K6 schrieb:
Die Begriffe sind verwandt, das stimmt. Allerdings unterscheiden sie sich eindeutig. Nimm zum Beispiel das Militär: Die strategische Führung gibt Anweisungen heraus, die der Erfüllung des Gesamtauftrages dienen. Also beispielsweise: "Ort A erobern" oder "Fabrik B zerstören".
auch das ist unfug. des einen strategie ist des anderen taktik.
Wenn man das Beispiel weiter führt ist die Strategie des einen dann wieder Gebiet G zu erobern, wobei die Strategie des Vorgesetzten dann wieder ist die Resourcen zu sichern etc. Es gibt immer einen, der eine höhere Strategie besitzt.
-
mal ein beispiel von mir: http://www.c-plusplus.net/forum/viewtopic-var-t-is-130564-and-postdays-is-0-and-postorder-is-asc-and-start-is-150.html
die kommentare sollen da nicht nur zeilen oder schnittstellen erklären oder gar den dateinamen der datei zeigen, in dem sie stehen, sondern sie sollen irgendwie dafür sorgen, daß man den code von oben nach unten wie eine kleine geschichte lesen kann. und dafür gips keine starren regeln.
hab diesmal immer nur oberhalb der zu beschreibenden zeile oder der zu beschreibenden zeilen kommentiert. das muss aber nicht so sein. mal ein beispiel für durcheinander-kommentare:
der code passt zur aufgabe 5 des 23. bundeswettbewerbs informatik.
#include <vector> #include <algorithm> using namespace std; struct Rect { int x1, y1, x2, y2; }; template<typename T> class Vector{ private: T* data; public: Vector(size_t size){ data=new T[size]; } ~Vector(){ delete[] data; } T& operator[](size_t index){ return data[index]; } }; template<typename T> class Vector2D{ private: T* data; size_t sizeX; public: Vector2D(size_t _sizeY,size_t _sizeX){ data=new T[_sizeY*_sizeX]; sizeX=_sizeX; } ~Vector2D(){ delete[] data; } T& at(size_t indexY,size_t indexX){ return data[indexY*sizeX+indexX]; } struct Proxy{ Vector2D& vector; size_t indexY; Proxy(Vector2D& _vector,size_t _indexY): vector(_vector), indexY(_indexY){ } T& operator[](size_t indexX){ return vector.at(indexY,indexX); } }; Proxy operator[](size_t indexY){ return Proxy(*this,indexY); } }; struct Point{ Point* up;//zeiger zu den nachbarn Point* right; Point* left; Point* down; size_t upLen;//oder oben geht size_t rightLen;//wie weit es noch nach rechts public: Point(): up(0), right(0), left(0), down(0){ } }; int wpc1HelperSmall(const std::vector<Rect>& rects){ size_t rectsSize=rects.size();//werde ich eh noch brauchen if(rectsSize==0) return 0;//ups, hier schon int allX[rectsSize*2];//alle möglichen x-werte // Vector<int> allX(rectsSize*2); int allY[rectsSize*2];//alle möglichen y-werte // Vector<int> allY(rectsSize*2); size_t allXSize=0;//so viel hab ich schon gesammelt size_t allYSize=0;//dito //alle x- und y-werte sammeln for(vector<Rect>::const_iterator i=rects.begin();i!=rects.end();++i){ allX[allXSize++]=i->x1; allX[allXSize++]=i->x2; allY[allYSize++]=i->y1; allY[allYSize++]=i->y2; }Das war wohl ein "strategischer kommentar".
//na, das ging doch wie apfelkuchenessen //am besten, ich werfe erstmal die doppelten werte raus. sort(&allX[0],&allX[0]+allXSize); allXSize=unique(&allX[0],&allX[0]+allXSize)-&allX[0]; sort(&allY[0],&allY[0]+allYSize); allYSize=unique(&allY[0],&allY[0]+allYSize)-&allY[0]; //und das ging auch wie apfelkuchenessen. das motiviert mich jetzt aber. //vielleicht mal ein raster aller möglichen eckpunkte aufspannen Point points[allXSize][allYSize]; // Vector2D<Point> points(allXSize,allYSize); //sehr fein. habe alle punkte, und die strecken sind die zeiger dazwischen. //die strecken einzutragen, sollte auch kein enormes problem sein. sie stehen //ja recht klar in den rechtecken drin for(vector<Rect>::const_iterator i=rects.begin();i!=rects.end();++i){ //werte in arrayindizes umsetzen int x1=lower_bound(&allX[0],&allX[0]+allXSize,i->x1)-&allX[0]; int x2=lower_bound(&allX[0],&allX[0]+allXSize,i->x2)-&allX[0]; int y1=lower_bound(&allY[0],&allY[0]+allYSize,i->y1)-&allY[0]; int y2=lower_bound(&allY[0],&allY[0]+allYSize,i->y2)-&allY[0]; //weil meine schleifen nur vorwärts laufen if(x1>x2) swap(x1,x2); if(y1>y2) swap(y1,y2);Hier hab ich gar nicht kommentiert, was der code macht, sondern warum.
//die beiden waagerechten linien des rechtecks eintragen for(int x=x1;x!=x2;++x){ points[x][y1].right=&points[x+1][y1]; points[x+1][y1].left=&points[x][y1]; points[x][y2].right=&points[x+1][y2]; points[x+1][y2].left=&points[x][y2]; } //die beiden senkrechten linien des rechtecks eintragen for(int y=y1;y!=y2;++y){ points[x1][y].up=&points[x1][y+1]; points[x1][y+1].down=&points[x1][y]; points[x2][y].up=&points[x2][y+1]; points[x2][y+1].down=&points[x2][y]; } } //jetzt habe ich alle strecken eingetragen. es sollte nun durchaus möglich sein, //alle daraus bildbaren rechtecke zu zählenUnd diese sorte kommentare sind auch ganz nett. nach dem code nochmal in erinnerung rufen, was wir alles schon haben.
//den punkten noch beibringen, wie weit sie nach rechts können for(size_t py=0;py<allYSize;++py){ size_t rightLen=0; size_t px=allXSize; while(px--){ Point* lu=&(points[px][py]);//links unten läuft über alle möglichen punkte if(lu->right) ++rightLen; else rightLen=0; lu->rightLen=rightLen; } } //den punkten noch beibringen, wie weit sie nach oben können for(size_t px=0;px<allXSize;++px){ size_t upLen=0; size_t py=allYSize; while(py--){ Point* lu=&(points[px][py]);//links unten läuft über alle möglichen punkte if(lu->up) ++upLen; else upLen=0; lu->upLen=upLen; } } size_t result=0; //ich laufe über alle punkte und zähle von jedem punkt aus nur die rechtecke, //die diesen punkt als untere linke ecke haben for(size_t py=0;py<allYSize;++py){ for(size_t px=0;px<allXSize;++px){ Point* lu=&(points[px][py]);//links unten läuft über alle möglichen punkte //durch die vorverarbeitung, das zählen von rightLen und upLen für jeden //punkt, brauche ich nicht alle 4 seiten des rechtecks abzufahren, sondern nur 2 //und kann dann direkt nachschauen, ob die anderen beiden seiten sich schneiden Point* ru=lu->right;//rechts unten for(size_t rightLen=1;rightLen<=lu->rightLen;++rightLen,ru=ru->right){ Point* lo=lu->up;//links oben size_t minUpLen=min(lu->upLen,ru->upLen);//brauche nur soweit hoch, wie //beide, die kleinste der beiden seiten (also links (von lu aufwärts) //und rechts (von ru aufwärts) lang sind. for(size_t upLen=1;upLen<=minUpLen;++upLen,lo=lo->up){ if(lo->rightLen>=rightLen)//wenn von lo es weiter nach rechts geht, als ich //von lu aus nach ru gelaufen bin, schließt diese gerade das rechteck ++result; } } } } return result; } int wpc1HelperBig(const std::vector<Rect>& rects){ size_t rectsSize=rects.size();//werde ich eh noch brauchen if(rectsSize==0) return 0;//ups, hier schonWar das jetzt ein taktischer kommentar?
// int allX[rectsSize*2];//alle möglichen x-werte Vector<int> allX(rectsSize*2); // int allY[rectsSize*2];//alle möglichen y-werte Vector<int> allY(rectsSize*2); size_t allXSize=0;//so viel hab ich schon gesammelt size_t allYSize=0;//dito //alle x- und y-werte sammeln for(vector<Rect>::const_iterator i=rects.begin();i!=rects.end();++i){ allX[allXSize++]=i->x1; allX[allXSize++]=i->x2; allY[allYSize++]=i->y1; allY[allYSize++]=i->y2; } //na, das ging doch wie apfelkuchenessen //am besten, ich werfe erstmal die doppelten werte raus. sort(&allX[0],&allX[0]+allXSize); allXSize=unique(&allX[0],&allX[0]+allXSize)-&allX[0]; sort(&allY[0],&allY[0]+allYSize); allYSize=unique(&allY[0],&allY[0]+allYSize)-&allY[0]; //und das ging auch wie apfelkuchenessen. das motiviert mich jetzt aber. //vielleicht mal ein raster aller möglichen eckpunkte aufspannen // Point points[allXSize][allYSize]; Vector2D<Point> points(allXSize,allYSize); //sehr fein. habe alle punkte, und die strecken sind die zeiger dazwischen. //die strecken einzutragen, sollte auch kein enormes problem sein. sie stehen //ja recht klar in den rechtecken drin for(vector<Rect>::const_iterator i=rects.begin();i!=rects.end();++i){ //werte in arrayindizes umsetzen int x1=lower_bound(&allX[0],&allX[0]+allXSize,i->x1)-&allX[0]; int x2=lower_bound(&allX[0],&allX[0]+allXSize,i->x2)-&allX[0]; int y1=lower_bound(&allY[0],&allY[0]+allYSize,i->y1)-&allY[0]; int y2=lower_bound(&allY[0],&allY[0]+allYSize,i->y2)-&allY[0]; //weil meine schleifen nur vorwärts laufen if(x1>x2) swap(x1,x2); if(y1>y2) swap(y1,y2); //die beiden waagerechten linien des rechtecks eintragen for(int x=x1;x!=x2;++x){ points[x][y1].right=&points[x+1][y1]; points[x+1][y1].left=&points[x][y1]; points[x][y2].right=&points[x+1][y2]; points[x+1][y2].left=&points[x][y2]; } //die beiden senkrechten linien des rechtecks eintragen for(int y=y1;y!=y2;++y){ points[x1][y].up=&points[x1][y+1]; points[x1][y+1].down=&points[x1][y]; points[x2][y].up=&points[x2][y+1]; points[x2][y+1].down=&points[x2][y]; } } //jetzt habe ich alle strecken eingetragen. es sollte nun durchaus möglich sein, //alle daraus bildbaren rechtecke zu zählen //den punkten noch beibringen, wie weit sie nach rechts können for(size_t py=0;py<allYSize;++py){ size_t rightLen=0; size_t px=allXSize; while(px--){ Point* lu=&(points[px][py]);//links unten läuft über alle möglichen punkte if(lu->right) ++rightLen; else rightLen=0; lu->rightLen=rightLen; } } //den punkten noch beibringen, wie weit sie nach oben können for(size_t px=0;px<allXSize;++px){ size_t upLen=0; size_t py=allYSize; while(py--){ Point* lu=&(points[px][py]);//links unten läuft über alle möglichen punkte if(lu->up) ++upLen; else upLen=0; lu->upLen=upLen; } } size_t result=0; //ich laufe über alle punkte und zähle von jedem punkt aus nur die rechtecke, //die diesen punkt als untere linke ecke haben for(size_t py=0;py<allYSize;++py){ for(size_t px=0;px<allXSize;++px){ Point* lu=&(points[px][py]);//links unten läuft über alle möglichen punkte //durch die vorverarbeitung, das zählen von rightLen und upLen für jeden //punkt, brauche ich nicht alle 4 seiten des rechtecks abfahren, sondern nur 2 //und kann dann direkt nachschauen, ob die anderen beiden seiten sich schneiden Point* ru=lu->right;//rechts unten for(size_t rightLen=1;rightLen<=lu->rightLen;++rightLen,ru=ru->right){ Point* lo=lu->up;//links oben size_t minUpLen=min(lu->upLen,ru->upLen);//brauche nur soweit hoch, wie for(size_t upLen=1;upLen<=minUpLen;++upLen,lo=lo->up){ if(lo->rightLen>=rightLen) ++result; } } } } return result; } int wpc1(const std::vector<Rect>& rects){ if(rects.size()<128) return wpc1HelperSmall(rects); return wpc1HelperBig(rects); }übrigens gefällt mir der name "strategischer kommentar" ganz gut. besonders bei diesen kommentaren, die ich schon stehen habe, bevor der code getippt wird. manchmal plane ich nämlich in pseudocode und dann bleibt die planung einfach als kommentar stehen.
Zug sageZug(const Stellung *stellung) { //Falls ich anfange, werfe ich die 4 if (stellung->spielAnfang()) return 4; //Sonst mache ich einfach den letzten Zug nach, falls er erlaubt ist Zug z=stellung->sageLetztenZug(); if(stellung->istGueltig(z)) return z; //Falls nicht, nehme ich irgend einen return stellung->sageZufallsZug(); }ne halbe stunde vorher sah das noch so aus:
Zug sageZug(const Stellung *stellung) { //Falls ich anfange, werfe ich die 4 //Sonst mache ich einfach den letzten Zug nach, falls er erlaubt ist //Falls nicht, nehme ich irgend einen }
-
volkard schrieb:
finix schrieb:
wisser schrieb:
Wenn ihr glaubt, einen Kommentar zu benötigen, refaktorisiert den Code, so das jeder Kommentar überflüssig wird.
Ach ja? Helf mir mal aus, was soll ich hier tun:
/** * <API Docs> */ void foo( bar const& b ) { // using algorithm x to accomplish foo // Rationale: bla bla blurb, etc lots of; code goes(here); // following line [does Y|is equivalent to code Z] some var = highly * optimised (obfuscated) % computation; }man kann an beispielen mit foo und bar nicht razusfinden, was hübsche kommentare sind.
da ich mir aussuchen kann, was fuu und blubs bedeuten, hier die stark verbesserte version:
void blaBlaBlurbByX( bar const& b ) { lots of; code goes(here); some var = Y/Z(...); }0/3 Punkte
-
Die Regel ist doch ganz einfach: Erkennt man nicht auf einen Blick was der Code macht, muss ein Kommentar hin.
class Auto { public void betanke(double liter) { if ( tank.getLiter() + tank.getKapazität() < liter ) { fahreZuTankstelle(); öffneTank(); while ( !tank.istVoll() ) tank.betanke(liter); bezahle(); } } }Alles Selbsterklärend der Code -> keine Kommentare.
-
DEvent schrieb:
if ( tank.getLiter() + tank.getKapazität() < liter )die zeile hab ich nicht kapiert. würde hier ein kommentar helfen?
-
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
-
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?
-
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.
-
da muss kein kommentar hin. der code muss refaktorisiert werden
-
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 seinpublic void volltanken()