[Jann Hendrik]

In dieser Umfrage geht es um Kommentare im Quelltext.

Für wie wichtig hältst du Kommentare im Quelltext?


Solltet Ihr an dieser Umfrage teilnehmen, würden wir uns über eine Begründung der eigenen Antwort freuen. Eine Diskussion unter den Teilnehmern dieser Diskussion ist ausdrücklich erwünscht.

Die Ergebnisse der Umfrage kann von jedem eingesehen werden.

[mr1st]

Hallo,

da ich nur hobbymäßig programmiere und quasi nie was veröffentliche, mache ich nur Kommentare, wenn ich Lust dazu hab. Ist irgendwie oft frustrierend, für 'nen Kommentar mehr Zeit zu verbraten als für die ganze Klasse

Es grüßt,
mr1st

[FloB]

Kommentare halte ich für unverzichtbar, aber ich persönlich halte das selten ein (siehe m1rst). Oder ich schreibe nur kurze Wortkombinationen, die nicht unbedingt für einen Außenstehenden aussagekräftig sind.

[Flor1an]

Ich glaube ich Kommentiere zu oft an Stellen die selbsterkärend sind, dafür Kommentiere ich dann weniger das Gesamte. Also kurze Passangen kann man dann nachvollziehen aber was das Skript insgesamt macht bleibt verborgen

Aber ansonsten ist es in einem Projekt an dem mehrere Leute arbeiten oder das so groß ist dass man daran länger sitzt bzw. später nochmal in den Code rein muss, unverzichtbar. Nur bei ganz kleinen Sachen wie ein Kontaktformular oder soetwas kann ich grad noch ohne Kommentare verkraften.

[$traight-$hoota]

Ich sehe das ähnlich, Kommentare sind eigentlich unverzichtbar und helfen auch bei privaten Projekten sehr viel, wenn man nach einer gewissen Zeit wieder am Code rumarbeitet.
Aber leider vernachlässige ich ordentliches Kommentieren auch viel zu oft...

[Neq']

Ordentliches Dokumentieren ist für mich sehr wichtig und gehört zum Guten Stil. Ich dokumentiere viel und regelmäßig. In einer Klasse wird sowieso jede Eigenschaft und Methode dokumentiert. Meiner Meinung nach macht es die OOP einem sowieso etwas leichter zu dokumentieren als prozedural geschriebener Code.

[Artemis]

Ich halte es auch so, dass ich Kommentare als genauso wichtig finde, wie den Code selber, halte mich aber selber auch nur zu 50% dran.

[Bleistift]

Kommentieren ist wichtig, ja. Aber viel wichtiger sind aussagekräftige Variablen-Namen. Also nicht foo, bar, i, x, z etc.
Auch wichtig ist, dass die Kommentar sinnvoll sind. Also nicht:

PHP-Code:

<?php
// $i wird um 1 erhöht
$i++;
?>

[Artemis]

Ich habe immer das Problem, dass ich schnell was am Quelltext ändern muss, und mir dann nicht kommentiere, was ich geändert habe, und was das neue jetzt macht.

[Hobbyuser]

Hi @ll

ich hab auch auf unverzichtbar geklickt und halte mich auch bei produktiven Projekten dran. Wobei man die Funktion des Scripts/Programms anhand der Kommentare nachvollziehen kann. Falls es wichtig ist werden auch Werte von Variablen kommentiert.

Gruß
Hobbyuser

[MrNiceGuy]

Auch wenn ich selber eigentlich nie Kommentare setze, denke ich dennoch, dass es - gerade bei großen Projekten - unverzichtbar ist, damit andere Leute sich auch in den Quellcode einlesen können. Allerdings sollte man aufpassen, dass man nicht zu viel kommentiert, denn irgendwie passt auch hier: Weniger ist mehr. So viel wie nötig, so wenig wie möglich sollte da der Weg sein, damit es auch nicht ausschweifend wird und man erst Romane lesen muss, bevor irgendwann mal erklärt steht, wie was laufen soll.

[xardias]

Naja kommt immer drauf an. Wichtiger als den Programmablauf zu kommentieren ist denke ich das Kommentieren der Methoden/Klassen/etc um deren Zweck und Verhalten zu erläutern.

In der Regel halte ich das Kommentieren für unverzichtbar. Erst recht wenn man Bibliotheken oder Frameworks entwickelt.
Sonst würde ich das davon abhängig machen ob andere Leute mit an dem Code arbeiten. Wenn man nur selbst dran bastelt sollte man davon ausgehen können dass der code übersichtlich genug ist dass man selbst ihn in 2 Monaten auch noch versteht Wenn nicht sollte man an seinem Programmierstil arbeiten *g*

[Basti]

Ich benutze praktisch gar keine Kommentare, versuche aber den Code s zu strukturieren, dass er lesbar ist. Für mich ist immer die Frage, ob das Verstehen einer Erklärung einfacher ist, als das Lesen des Codes, der das Verständnis des Problems ja letztlich ausdrückt. Mitunter ist ein kleiner hinweis aber sinnvoll.

PHP-Code:


$sPageName = $this->Request->get('pagename');

$Page = $this->Pages->getByName($sPageName);

if (is_null($Page)) {

     if ($this->Pages->pageMoved($sPageName)) {

        $sNewPageName = $this->Pages->getNewPageName($sPageName);
        return $this->redirect($sNewPageName, HTTP_PERMANENTLY);
    }

    return $this->error404();
}

if (!$this->User->hasPermission($Page, 'edit'))
    return $this->noRights();

$this->toView('page', $Page); 


Ist jetzt nur mal so dahin geschrieben, aber was wollte man da noch kommentieren?

Schnittstellen sollten gut dokumentiert werden und, was mir in aller Regel fehlt, sind Einführungen in die Konzepte, die einem System zugrunde liegen (liegt wohl daran, dass die, die die Dokus schreiben könnten gar nicht mehr anders denken können, als genau in den umgesetzten Konzepten und dann gar nicht mehr auf die Idee kommen, wo ein Einsteiger hängen bleiben kann, weil er ganz andere Arbeitsweisen im Kopf hat). Aber den Code selbst kommentiere ich praktisch überhaupt nicht mehr. Bis auf kleinere Erklärungen (vielleicht bei einem RgExp), wenn etwas sich nicht selbst gleich erschließt, stehen da nur verweise auf Code-Quellen drinnen und natürlich all diese merkwürdigen Einträge hier:

PHP-Code:

//@todo: 


Basti

PS:
Mit Lust hat das nichts zu tun, daher keine Antwort in der Umfrage von mir.

[xardias]

Ich habe gerade gemerkt dass ich ab und zu doch kommentare in den programmablauf selbst mache.
Aber eigentlich nur bei komplexeren Algorithmen die man schlecht in mehrere Methoden kapseln kann (weil sie von zu vielen Parametern abhängen oder die Funktion nicht direkt ersichtlich ist)
Nur als beispiel:

int main(uint64 spe_id, uint64 datap) {
	BenchmarkData data;
	int i;
	char* buffer;
	
	// Receive benchmark data
	mfc_write_tag_mask(1<<DMA_TAG);
	mfc_get(&data, datap, sizeof(BenchmarkData), DMA_TAG, 0, 0);
	spu_mfcstat(MFC_TAG_UPDATE_ALL); 
	
	// Create some test data. 
	buffer = malloc(data.transferSize);

	// Warmup transfer
	for(i=0; i<data.transferRepeats; ++i) {
		mfc_put(buffer, data.targetAddress, data.transferSize, DMA_TAG, 0, 0);
		spu_mfcstat(MFC_TAG_UPDATE_ALL);
	}

	// Benchmark transfer
	startTimer();
	for(i=0; i<data.transferRepeats; ++i) {
		mfc_put(buffer, data.targetAddress, data.transferSize, DMA_TAG, 0, 0);
		spu_mfcstat(MFC_TAG_UPDATE_ALL);
	}
	data.transferTime = getElapsedMilliseconds();

	// Send benchmark data back to PPU
	mfc_put(&data, datap, sizeof(BenchmarkData), DMA_TAG, 0, 0);
	spu_mfcstat(MFC_TAG_UPDATE_ALL);
	return 0;
}

[Jann Hendrik]

Zitat von Basti

daher keine Antwort in der Umfrage von mir.

finde ich eine interessante Begründung!

zumal es sowohl unter 'ich brauche daher keine Kommentare' fallen könnte, wie auch unter 'gut kommentiert' - wobei gut eben so viel wie nötig und so wenig wie möglich ist...

[MrNiceGuy]

Was mir eben noch eingefallen ist: Ich finde eindeutige Variablennamen besser als jeden Kommentar! Wenn statt $name eben $stringUserName genommen würde, weiß man beim Lesen auch gleich, welchen Inhalt die Variable hat und von welchem Typ sie ist. Ich schreibe mitlerweile nurnoch ellenlange Variablennamen, kann dafür aber auch ohne groß überlegen zu müssen jederzeit auf den Variablennamen schließen. Sieht zwar etwas komisch aus im Quellcode, ist aber ungemein praktisch.

[Jojo]

Ich persönlich halte eine Dokumentation (à la JavaDoc, PHPDoc, Doxygen) allgemein für sinnvoller als einfache Kommentare.
Gerade weil man in späteren Phasen der Programmierung dann nicht so sehr an den bereits bestehenden Code gebunden ist.
Im Grunde steht deshalb vor jeder Funktion/Klasse bei mir eine kurze Erklärung, was die Klasse macht, was reinkommt und ob und wie wieder etwas rauskommt.

Inline-Comments (kann man das so nennen?) stehen bei mir nur in der Enwicklungsphase eines Codes, damit ich den momentanen Überblick behalte, wenn der Code an Komplexität zunimmt (obwohl das ja eigentlich ein Zeichen für schlechte Planung ist... )

Ansonsten sind in "fertigen" Klassen bei mir eher Doku-Comments zu finden.

Das gilt bei mir allerdings auch nur für die Idealbedingung. Gerade wenn ich einen Codeflash bekomme, bleiben Kommentare (zu meinem Leidwesen in späteren Phasen) auf der Strecke.

[Artemis]

Jo, so wie Lutz mache ich das auch: sprechende Namen, mit einem Kürzel für den Dateitypen. s für String, i für Int, o für Objekt usw.

Das sieht dann eben so aus:
$sUserName
$iEatenCakes
$oCookie

[Jann Hendrik]

Ich bin gerade am überlegen, ob die These, dass die Variablen-Bezeichnung nicht auch eine Art Kommentare sind, richtig sein könnte.

Denn im Prinzip sind es ja nicht einfach nur Buchstabenfolgen, die Werte zwischenspeichern, sondern durch die (un-)geschickte Benennung auch noch weitere Infos geben können.

[Flor1an]

Wobei ich diese Bezeichnung von Variablen nicht schön finde. Es erschwert mir das lesen im Quelltext.

Zum anderen bedeutet der Buchstabe noch lange nicht dass auch das drinnen Steckt was drauf steht! Der Programmierer hofft nur dass es auch diesem Zustand entspricht. Aber da PHP so gesehen keine Typen kennt kann alles mögliche drinnen stecken.