Wie schreibt man Kommentare "schön"

Hallo,

ich habe mir Gedanken zu Kommentaren in Programmen gemacht.

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

Also, hinter dem Code

x=x*x //berechnet das Quadrat

Oder besser über dem Code?

//berechnet das Quadrat
x=x*x

Oder unter dem Code?

x=x*x 
//berechnet das Quadrat

Wieviel Platz sollte man lassen zwischen einem Kommentar und der nächsten, nicht zum Kommentar gehörenden Codezeile ?

finix

/**
 * Function foo does bla bla blurb, etc.
 * (Oh, btw, this comment is readable by a tool like doxygen.)
 */
void foo()
{
  /*
   The following algorithm works like this:
   bla bla
   [ascii-art]
   and so on
  */

  bar b;
  b.self_explanatory();
  also self(explanatory());
  b.do_something() % 42; // Computing some value here
  finish(b);
}

GPC

Hallo,

kommentare sind, wie code-style allgemein, Geschmackssache. Dennoch denke ich, dass es sinnvoller ist, einen einzeiligen Kommentar über dem Code zu platzieren. Kurze Kommentare könnte man zwar hinter dem Code platzieren, aber ich bin ein Freund von Konsistenz im Quellcode. Außerdem stört es imo den Lesefluss, wenn 'n Kommentar hinter ner Zeile Code auftaucht.

Wieviel Platz sollte man lassen zwischen einem Kommentar und der nächsten, nicht zum Kommentar gehörenden Codezeile ?

Imo eine Leerzeile. Zu viele Leerzeilen wirken störend und zu wenige sind auch nix

Aber hey, das ist halt höchst subjektiv

MfG

GPC

rüdiger

MisterX schrieb:

Also, hinter dem Code
x=x*x //berechnet das Quadrat

Der Kommentar ist in jeder Form dämlich. Ein Kommentar sollte ja in der Regel nicht erklären was eine einzelne Zeile macht, vor allem wenn es so offensichtlich ist.

Kommentare sollte man sparsam verwenden, um Dinge zu erklären die nicht offensichtlich sind (sprich irgend welche Hacks zu erklären), um die API zu dokumentieren oder um Stellen zu markieren, an denen man noch weiter arbeiten muss (etwa in der Form //TODO ...).

Wenn sich ein Kommentar nur auf eine Zeile bezieht, schreibe ich ihn in der Regel direkt in der Zeile (oder aus Platzgründen nach der Zeile etwas eingerückt). Bei Kommentaren die sich über mehrere Zeilen oder Funktionen erstrecken, schreibe ich diese immer davor (wobei sich dort C-Style Kommentare ala /**/ anbieten).

Für APIs lohnen sich automatische Werkzeuge, wie Doxygen.

Blue-Tiger

Ein Styleguide, den ich vor Urzeiten mal gelesen hab, hat folgende Konvention vorgeschlagen, die ich eigentlich immer zu folgen versuch:

* Strategische Kommentare
Kommentieren, was die darauffolgenden Zeilen so machen, und betreffen oft einen ganzen Block von Code (und sind oft ein guter Kandidat fuer etwas, was in eine eigene Funktion ausgelagert gehoert). Deshalb stehen sie zu Beginn dieses Blockes:

MainWindow::MainWindow(wxString title)
	: wxFrame (0, wxID_ANY, title)
{
	...

	// create some test-graphs
	Result* g = new Result("x^2 -30");
	Result* h = new Result("15*sin(x)"));
	Result* k = new Result("tan(x)");
	for (float i = -20; i <= 20; i += 0.1)
	{
		g->addPoint(i, i*i- 30);
		h->addPoint(i, 15*sin((float)i));
		k->addPoint(i, tan((float)i));
	}
	h->setPen(wxGREEN_PEN);
	k->setPen(wxCYAN_PEN);
	GraphData* graph1 = new GraphData(std::string("Graph 1"));
	graph1->addResult(*g);
	graph1->addResult(*h);

	...

oder:

// the rights are stored as 3bit, where the first bit tells if the user has the right
		// on the entry while it's still planned, the second one when its "to be approved" and
		// the last one when it's already accepted.
		$idx = 0;
		if (!strcmp($entry['status'], "to be approved")) $idx = 1;
		if (!strcmp($entry['status'],"approved")) $idx = 2;

* Taktische Kommentare
Taktische Kommentare sind hingegen etwas, was nur eine einzelne Zeile betreffen. Es geht da weniger darum, einen Ueberblick a la "die folgenden Zeilen machen dieses und jenes" zu geben, sondern nur den Sinn einer einzelnen Zeile zu erklaeren. Deshalb stehen diese idealerweise gleich hinter dieser Zeile z. B.

$maxstart = util::toTimestamp(date('d-m-Y', $maxstart)); // convert starttime to the BEGINNING of the day

Logisch geht sich das aber nicht immer aus, dann muss man sie eben vorne hin schreiben.

// #&013; is the html-entity for a linebreak (works only in IE)
		$mouseoverdetails = str_replace('\n', '
', $details);

So mach ich's, aber wie gesagt, das ist reine Geschmackssache.

schon merkwürdig, dass jemand die begriffe "strategie" und "taktik" zur unterscheidung benutzt...

Blue-Tiger

öaslr möwl35o .as,dfmaüw0 schrieb:

schon merkwürdig, dass jemand die begriffe "strategie" und "taktik" zur unterscheidung benutzt...

Wenn du den Unterschied nicht kennst dann schlag ihn halt nach http://de.wikipedia.org/wiki/Strategie#Abgrenzung

Nanyuki

Also, "schöne" Kommentare gibt's nicht, nur nichtexistente Kommentare sind gute Kommentare.

Aber wenn man unbedingt welche machen muss...
hinter die Zeile bringt gar nichts, lieber in eine eigene Zeile davor, dann werden sie vielleicht auch gelesen.

imho ist es viel wichtiger was in den kommentaren steht, nicht wo diese stehen:

entityhandler[2].doAction(4); // führt aktion 4 im index der zweiten entity aus

aehm ja..

entityhandler[2].doAction(4); // Animationsschleife fürs laufen

man sieht sowas häufig, wenn man leute kennt die grade mit irgendwelchen programmiersprachen anfangen:

something= another+foo; //something ist nun die summe aus another+foo

ein kommentar sollte den sinn einer zeile beschreiben, nicht was in der zeile steht

Blue-Tiger schrieb:

Wenn du den Unterschied nicht kennst dann schlag ihn halt nach http://de.wikipedia.org/wiki/Strategie#Abgrenzung

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

""

mantiz

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.

DrGreenthumb

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
{
}

volkard

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.

Gregor

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#Abgrenzung

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

finix

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;
}

volkard

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(...);
}

volkard

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.

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

Wie schreibt man Kommentare "schön"