Besser später kommentieren?

tntnet

Richtiges Kommentieren ist schon eine Kunst für sich. Ich bin persönlich nicht gut im Kommentieren und komme in letzter Zeit mehr und mehr dahinter, warum.

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

Apollon

Und bitte nicht Kommentare mit Dokumentation verwechseln. Kommentare sind eigentlich nur dann notwendig, wenn man einen Hack/Workaround einbaut.

EDIT: Argh! Quetscht sich wieder einer dazwischen.

Artchi

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.

Ich schreibe Kommentare, weil ich festhalten möchte, was ich mir in dem Moment dabei denke. Also ich schreibe gleich hin, was der Code meiner Absicht nach tuen soll.

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

GPC

Artchi schrieb:

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.

nep

Ein anderer Ansatz ist noch folgender:
Bevor du eine Funktion schreibst, schreibst du ganz am Anfang erst mal einen kompakten Kommentar was du in der Funktion machen willst und wie du es tust. Dann codest du das erst und orientierst dich am Kommentar. Vorteil ist, dass man sich schon im Vorfeld *richtige* Gedanken macht und nicht gleich loscodet (und so merkt man auch oft schon was man evtl. besser machen kann).

Artchi schrieb:

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?

Artchi

Library-User = Public = API
Developer = Intern

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

Stelfer

ich bevorzuge eine kleine doku bevor ich irgendwas lesen will
suche ich nach meinen grünen zeilen, halte an und sehe schon beim runterscrollen was es ist und was es macht.

ich muss 0 Zeilen quellcode lesen

Blue-Tiger

Ich tendier manchmal dazu, manche Bloecke (3 - 10 loc) mit einem Kommentar drueber zu versehen, der beschreibt was der Block tut. Zwar sieht man aus dem Block selber meistens auch, wozu er da ist, aber wenn ich den Code nur so ueberfliege gehts schneller, wenn ich nur den Kommentar durchlese, anstatt mich durch die ganzen Codezeilen durchdenk. Das sieht dann z. B. so aus:

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