// der php hacker

// archiv

Über die Crux mit dem Kommentieren

Geschrieben am 04. Nov 2010 von Cem Derin

Ausnahmslos jeder Entwickler kennt das Problem: Schlecht kommentierter Code, der leider alles andere als selbstbeschreibend ist. Und Ausnahmslos jeder Entwickler hat selbst schon einmal solchen Code produziert. Sei es aus Faulheit oder aus vielleicht doch aus Unwissenheit – irgendwann mussten wir uns den Schuh mal anziehen. Ich möchte mal ein bisschen aus dem Nähkästchen plaudern, auch wenn ich mich damit heute mal nicht mit Ruhm bekleckere. Aber man muss ja auch mal in den sauren Apfel beissen können. Genug mit dem Phrasengedresche.

Früher, da war ja alles ganz anders, mein Kind!

Als ich meine ersten Zeilen Code geschrieben habe, da sah ja alles ganz anders aus. Kommentiert habe ich nur sehr wenig. Ich hab hier sogar noch ganz alten Code von mir gefunden, den ich euch nicht vorenthalten möchte!

	function user_overview($link) {
		include('../src/inc/config.php');
		if(!is_numeric($_GET['page'])) {
			$_GET['page'] = 1;
		}
		if($_GET['page'] <= 0) {
			$_GET['page'] = 1;
		}
		$curpage = $_GET['page'] - 1;
		$offset = $curpage * $G_MAX_USER_OVERVIEW;
		$query = "SELECT id, username FROM userdata_core LIMIT ". $offset.", ". $G_MAX_USER_OVERVIEW;
		$result = mysql_query($query, $link);
		while($data = mysql_fetch_array($result)) {
			$add = array_simple($add, "{USERNAME}", $data['username']);
			$add = array_simple($add, "{ID}", $data['id']);

			// In Loop-Array
			$user = array_loop($user, $add);
			unset($add);
		}

		// Navigation erstellen
		$query = "SELECT COUNT(id) FROM userdata_core";
		$result = mysql_query($query, $link);
		$data = mysql_fetch_array($result);
		$pages = ceil($data['COUNT(id)'] / $G_MAX_USER_OVERVIEW) - 1;
		$nav = create_navigation($curpage, $pages);

		// Template
		$source = file_get_contents('src/templates/user/overview.html');
		$source = parse_loop($source, $user, "{USER}");
		$source = parse_simple($source, $nav);
		return $source;
	}

Wir sehen: Kaum Kommentare, so wirklich versteht man nicht auf den ersten Blick, was ich da überhaupt mache. Zu meiner Verteidigung: Dieser Code stammt aus einem ziemlich  über das Knie gebrochene Projekt von vor über 6 Jahren. OOP war noch Neuland für mich, es musste schnell gehen, das Budget war klein.

In dem Projekt allerdings nutzte ich eine „Template-Engine“, die ich zuvor geschrieben habe. Komplett unkommentiert. Das habe ich dann im Anschluss nachgeholt, leider mit falsch Verstandenem Eifer. Jetzt war jede Zeile kommentiert, aber verstanden hat die Funktionen immer noch keiner (oder zumindest nicht, warum man nicht die nativen genommen hat). Veröffentlicht hab ich diese im Rahmen des „Developers Shame Day“. Deswegen nicht hier nochmal …

Jedenfalls: In den folgenden Jahren lebte ich also erst einmal nach der Devise: Um so mehr, desto besser. Ich habe alles mit Kommentaren zugepflastert. Dass das ungefähr genau so „nützlich“ ist wie überhaupt nicht zu kommentieren, merkt man erst, wenn jemand anders an den Code muss.

Wie also richtig kommentieren?

Gleichberechtigt mit guter Kommentier-Mentalität steht meiner Meinung nach die selbstbeschreibende Benamung von Klassen, Methoden, Variablen und Funktionen. Nichts ist Schlimmer als „getVarItmByFltr()“ oder „handleThis“ lesen und auseinanderklamüsern zu müssen. Eine gute Benamung kann einen Kommentar ersetzen – jedenfalls fast. Warum nur fast, dazu später mehr. In meiner Pipeline liegt noch ein Artikel, der einige Grundsätze und Faustregeln aufstellt, wie man Methoden, Klassen und Funktionen benennen sollte, damit klar ist, was passiert – und manchmal eben auch, was nicht.

Warum gute Benamung Kommentare (per Definition) nicht komplett unnötig macht, ist die gute alte DocSyntax. Diese sorgt daür, dass automatische Übersichten über eine Klassenstruktur erstellt werden können, und diese mit „menschenlesbarem“ Text versehen wird. Dort können auch Benutzungshinweise und „Zu Erledigen“ Markierungen angelegt werden. Zuguterletzt ist der große Vorteil für PHP auch noch, dass diverse Typ-Informationen von der IDE genutzt werden.

Trotzdem: Wer sich so eine generierte Dokumentation mal angesehen hat, der wird mir zustimmen, dass es nur unwesentlich besser ist, als sich den Code direkt selbst anzuschauen. Es ist halt nach wie vor automatisch generiert. Und eins darf man nicht vergessen: Diese Doc-Dinger werden aus dem Kommentarblock über der Signatur genommen. Was in der Methode (oder Klasse) passiert, bedarf ggf. auch noch einer Erklärung. Dabei sollte man beachten, dass man selbst vielleicht die abgefahrene Notation toll lesen kann, oder selbst die Haversine-Formel im Schlaf aufsagen kann … dass anderen aber evtl. nicht so geht. Deswegen, auch wenn man Methoden klein und kompakt hält: Erklörungsbedarf wird irgendwo immer sein. Erkennt ihn – und dafür gibt es leider keine Faustregel. Sicher ist nur: Wenn ihr es nicht in einem Satz und Allgemein-Verständlicher Sprache sagen könnt, dann muss ein Kommentar her ;)

For the LOLs!

Damit wir nun nicht nur Staubtrocken herumphilosophiert haben, hier noch eine recht lustige Seite mit den lustigsten Fundstücken in Code-Comments (war mir übrigens schon vor dem Developers Shame Day bekannt).

(Auf stackoverflow.com gibt es auch so einen „Thread“).

Geschrieben in Entwicklung 3 Kommentare

#001
04. Nov 2010
Chris W

Deinen fast letzten Satz
“Wenn ihr es nicht in einem Satz und Allgemein-Verständlicher Sprache sagen könnt, dann muss ein Kommentar her”
würd ich noch erweitern:
“Wenn ihr es nicht in einem Satz und Allgemein-Verständlicher Sprache sagen könnt, dann versucht den Code so umzugestalten, dass ihr es könnt. In den sehr seltenen Fällen, in denen das unmöglich ist, muss ein Kommentar her”.
In “Clean Code” von Robert C. Martin – sehr gutes Buch das jeder Programmierer lesen sollte – gibts auch einen Abschnitt zur Kommentierung. Dein Satz mit der beschriebenen Erweiterung fasst den Abschnitt ganz gut zusammen :D


#002
04. Nov 2010
harald

“richtig kommentieren” bedeuted für mich auch die wahl einer geeigneten sprache — ich bevorzuge da englisch. kein witz: bei einem meiner ersten arbeitgeber vor vielen jahren gab es ein kleines shop-system, dass mein vorgänger in perl selbst entwickelt hatte. das system war an einigen stellen kommentiert. mein vorgänger war zu dieser zeit schon nicht mehr greifbar und die kommentare waren für mich leider vollkommen nutzlos — da in russisch.


#003
04. Nov 2010
Cem Derin

@Chris W: Stimmt, konkret geht es aber trotzdem um Kommentieren, und nicht wann und wie man refactoring betreiben soll. Nichtsdestotrotz ist es natürlich richtig.

@harald: Sehr gut, und eigentlich hätte ich wohl zugestimmt, würde ich nicht wissen, wie schlimm es ist, Kommentare von jemanden zu verstehen, der zwar auf Englisch geschrieben hat, es aber leider nicht beherrscht. So passiert vor ein paar Jahren … und noch frustrierender, wenn alles auf Deutsch hätte sein können – denn wir waren ja alle Deutschsprachig ;)

// kommentieren

// senden
theme von mir, software von wordpress, grid von 960 grid system. funktioniert in allen browsern, aber der safari bekommt das mit der schrift am schönsten hin.