PS: An die, die sich mit Interpunktion auskennen. Stimmt das da oben so?

im quelltext selber schreibe ich nurnoch die etwas unleserlichen sachen rein

Ist es eigentlich besser, wenn man seinen Code erst später kommentiert?

Nee, die Kommentare sollen ja gerade helfen den Code später noch schnell zu verstehen.

Aber ich mache das auch oft so, beim zweiten mal sieht man immer mehr.
Habe dafür aber auch schon oft vor altem Code gesessen, den ich dann nochmal neu analysieren musste.

Wenn ich anfange, Kommentare zu schreiben, ist die Ursache meistens der unleserliche Code. Ich fange dann recht schnell an, den Code umzustrukturieren und vor allen Dingen zu modularisieren, also in Funktionen aufzuteilen. Die Funktionen bekommen dann sprechende Namen, die sich den Kommentaren sehr ähneln. Das macht meinen Kommentar dann überflüssig. Aus einem komplizierten Vorgang etwa entsteht so etwas:

// mache dies
MacheDies();
// mache das
MacheDas();

Man erkennt, daß der Kommentar ursprünglich da war, um einen komplizierten Block zu erkären. Die Umstrukturierung macht den Kommentar überflüssig. Also war der Ansatz der Kommentierung schon falsch.

Daher meine Erkenntnis: Nicht kommentieren, was gemacht wird, sondern warum es gemacht wird. Was gemacht wird, sollte man durch lesbaren Code kommentieren. Warum es gemacht wird, kann ich algorithmisch nicht ausdrücken.

Und noch ein Wort zur ursprünglichen Frage: Wenn man den Code schreibt, weiß man am besten, warum man ihn macht. Später sind vieles Vermutungen. Daher sollten Kommentare gleich geschrieben werden. Das hilft auch beim sortieren der Gedanken und führt letzten endes zu besseren Code.

Tntnet

EDIT: Argh! Quetscht sich wieder einer dazwischen.

Manchmal sind aber Kommentare nötig, weil man selber nicht weiß, wie man den Code besser macht.

Was anderes ist eine Dokumentation des Codes. Hier muß ich sagen, hat die Eclipse-Guidline Recht: Funktionen die nicht dokumentiert sind, sind keine API-Funktionen.

D.h. wenn ich eine Library schreibe, muß ich auf jeden Fall alles dokumentieren, was für einen Library-User bestimmt ist.

So fällt mir die Fehlersuche leichter und das, was Marcus Refactoring nennt.

Guter Code braucht keine Kommentare. Weil wenn ich den Code lese, muß ich autom. interpretieren können, was er bedeutet. Ein kommentar ist einfach nur ein Interpretation des Codes. Eigentlich doppel-gemoppelt.

Hm, ich empfinde einen Kommentar als schlecht, wenn er den Code in natürlicher Sprache wiederholt ("interpretiert"). Ein für mich guter Kommentar erklärt z.B. welche Formel bei einer komplexen Berechnung zugrunde liegt oder gibt andere Infos wieder, die eben NICHT im Quellcode stehen.

Gibt aber auch Ausnahmen, wie z.B. die angesprochenen Funktionskommentare. Da ist es schon sinnvoll, wenn man dazuschreibt, wie die Parameter zu verwenden sind.

Guter Code braucht keine Kommentare. Weil wenn ich den Code lese, muß ich autom. interpretieren können, was er bedeutet. Ein kommentar ist einfach nur ein Interpretation des Codes. Eigentlich doppel-gemoppelt.

Manchmal sind aber Kommentare nötig, weil man selber nicht weiß, wie man den Code besser macht.

Was anderes ist eine Dokumentation des Codes. Hier muß ich sagen, hat die Eclipse-Guidline Recht: Funktionen die nicht dokumentiert sind, sind keine API-Funktionen.

D.h. wenn ich eine Library schreibe, muß ich auf jeden Fall alles dokumentieren, was für einen Library-User bestimmt ist.

Beim obersten Punkt stimm ich dir vollkommen zu, ich kommentiere auch recht sparsam, da der Code selbst schon das meiste sagt.

Aber ich finde man sollte alle Funktionen dokumentieren. Ich benutze doxygen für meine Dokumentation und hab einmal eine "public" Doku die die öffentliche Schnittstelle(n) beinhaltet und eine "developer" Doku die auch die privaten Funktionen und alles was dazu gehört mitdokumentiert.
Oder hast du dich nur auf die öffentliche Doku bezogen?

Klar kann man für das Devteam noch dokumentieren. Aber mir ging es um die API. Man muß den Satz "Funktionen die nicht dokumentiert sind, sind keine API-Funktionen." eher provokativ verstehen. Nach dem Motto "Du willst mir erzählen, das diese Funktion hier zur API gehört, hast sie aber nicht dokumentiert???"

ich muss 0 Zeilen quellcode lesen

def writeStats(outputDir):
	''' Writes all the statistics created so far, putting them into outputDir.'''

	dirs = _prepareDirectories(outputDir)

	# write games
	c = db.cursor()
	c.execute("SELECT id FROM games")
	games = c.fetchall()
	c.close()
	for data in games:
		try:
			gw = GameWriter(data[0], "../style.css")
			gw.write(dirs[0], dirs[2])
		except Exception, e:
			logging.error("an unexpected error occured while writing the file for game no. " 
				+ `data[0]` + " (the file might not have been created)")
			logging.debug(`e`)
#			raise

	# write players
	c = db.cursor()
	c.execute("SELECT id FROM players")
	players = c.fetchall()
	c.close()
	for data in players:
		try:
			pw = PlayerWriter(data[0], "../style.css")
			pw.write(dirs[1])
		except Exception, e:
			logging.error("an unexpected error occured while writing the file for player no. "
				+ `data[0]` + " (the file might not have been created)")
			logging.debug(`e`)

	# write indexfile
	players = [x[0] for x in players]
	games = [x[0] for x in games]
	_createIndexFile("style.css", outputDir, games, players)

Zwar koennte man die einzelnen Bloecke auch genauso gut in einzelne Funktionen auslagern, aber (z. B. auch in obigem Beispiel) lohnt sich dass nicht weil das eher zur "Zerstueckelung" von eigentlich zusammenengehoerigem Code beitragen wuerde, und deswegen nicht zur besseren Lesbarkeit beitragen wuerde, IMO.
Den Grossteil an Kommentaren machen bei mir - wie bei dem meisten anderen hier anscheinend auch - allerdings die "warum mach ich das auf diese Weise/ueberhaupt/an dieser Stelle/..." - Kommentare aus.

Aber das Ganze geht jetzt wohl schon zu weit in Richtung "Kommentierstil". Was die eigentliche Frage im Thread anging: Also mir passierts oefters, dass ich beim zweiten Lesen eines Kommentars den Kommentar nochmal komplett umschreib. Weil ich beim Zeitpunkt des Kommentierens mitten im Programmieren war und dann oft Dinge kommentiert habe, die im Nachhinein voellig offensichtlich waren, oder weil der Kommentar absolut keinen Sinn ergab (von Programmier- auf "normale" Sprache umschalten funktioniert bei mir manchmal nicht so gut ). Waehrend des Programmierens hat man (oder hab zumindest ich) oft so einen Tunnelblick, was dazu fuehrt dass manche Kommentare eben einfach "schlecht" sind.
Andererseits denk ich, dass manche Dinge wohl ueberhaupt unkommentiert blieben, wenn man den Code erst in einem zweiten Moment kommentieren wuerde