Captain Obvious Kommentare
Den Code zu schreiben war schwer, daher machen wir fleissig Kommentare. Zudem sind Kommentare immer ein Zeichen von Qualitätssoftware, richtig?
Nein.
Code sinnvoll zu kommentieren ist eine kleine Kunst für sich – allerdings stur alles zu kommentieren führt zu solchen Kommentaren:
/// <summary>
/// Home Controller
/// </summary>
public class HomeController : Controller
{
/// <summary>
/// Index Method
/// </summary>
/// <returns></returns>
public ActionResult Index()
{
ViewBag.Message = "Welcome to ASP.NET MVC!";
return View();
}
/// <summary>
/// Guess what?
/// </summary>
/// <returns></returns>
public ActionResult About()
{
return View();
}
}
Der Mehrwert solcher Kommentare ist gleich 0 – ausser vielleicht das man eine bestimmte “Quality Code Metric” ausgetrickst hat oder eine Regel befolgt hat. StyleCop & co. machen es ziemlich einfach ein regides Regelwerk zu erstellen.
Regeln und “weniger ist mehr”
Eine “wir kommentieren alles”-Regel ist aus meiner Sicht völlig unnütze und verleitet sogar dazu “falsche” Kommentare zu erstellen. Kommentare sollen den Code erklären – warum gibts dies und jenes. Das das die “HomeController” Klasse ist sehe ich selber und wie ein Konstruktor aussieht erkenne ich auch noch. Aber warum wird diese oder jene Prüfung vorgenommen? Was versteckt sich fachlich hinter dem Code?
Wer Code Kommentare inflationär einsetzt verringert auch das Empfinden der Projektmitglieder sich um die Kommentare zu kümmern. Resharper kann clevere Refactorings durchführen – aber die Kommentare müssen von Hand nachgezogen werden und wenn das keiner macht, “weil es so viele Kommentare gibt”, dann sind sie nur noch eine Belastung.
Meine Empfehlung beim Kommentieren:
- Warum wurde der Code so entwickelt? Das “wie” sieht man im Code.
- Regeln verleiten zu unnötigen Kommentaren, welche Zeit während der Entwicklung brauchen und besonders in bei der Pflege des Codes.
- Innerhalb des Teams sollte man sich auf eine Sprache einigen. Deutsch / Englisch Gemischt hat einen unschönen Beigeschmack.
- Immer im Hinterkopf behalten: Wird der Code durch den Kommentar bereichert? Wenn nicht, dann gibts keinen Kommentar. Auch gut(! – Kommentare sind kein MUSS!)
Wenn Kommentare zu lang werden…
In diesem Fall sollte man sich überlegen ob der Code am Ende nicht einfach zu kompliziert ist. Dutzende Zeilen der Erklärung können auch zeigen, dass eine Methode zu viele Aufgaben hat.
Weitere Meinungen zum Thema
Ayende Rahien und Jeff Attwood haben ebenfalls über diese (doch schon recht alte Thema) gebloggt.
Eure Meinung würde mich interessieren
Wie steht ihr dazu? Lieber alles kommentieren? Bin ich nur zu faul zum Schreiben? Welche Stilblüten habt ihr schon gesehen? Gibt es bei euch eine Code Kommentar Regel?
About the author
Written by Robert Mühsig
Hi, ich bin Robert Mühsig und bin Webentwickler und beschäftige mich mit Web-Frameworks auf dem Microsoft Web Stack und scheue mich auch nicht vor Javascript. Der Blog begann als "Problemsammelstelle und Lösungshilfe" und seitdem schreibe ich hier alles auf. Seit 2008 bin ich Microsoft MVP für ASP.NET. Treffen kann man mich online via Twitter (@robert0muehsig) oder hier.
Robert (INdotNET)
10. July 2012
Da stimm ich dir absolut zu!
Gerade die Architekten werden es nie lernen, dass eine aufgedrückte Regel die Qualität nicht besser macht. Da wäre es sogar hilfreicher, sich im Team mal zu unterhalten, anstatt es zu forcieren.
Eine Art von Kommentaren hast du vergessen:
//
// Dear maintainer:
//
// Once you are done trying to ‘optimize’ this routine,
// and have realized what a terrible mistake thar was,
// please increment the following counter as a warning
// to the next guy:
//
// total_hours_wasted_here = 25
//
(Gesehen im kostenfreien KaffeeKlatsch Magazin – Ausgabe 02/2012 – http://www.bookware.de/)
Holger Kreissl
10. July 2012
Ich stimme dem voll und ganz zu. Eine Kommentierungszwang führt unweigerlich zum Einsatz von GhostDoc oder Resharper CodeCleanUp mit Autokommentaren. Ich hatte im aktuellen Projekt gegen die Kommentarpflicht gewettert, jedoch wurde ich überstimmt. Das hat zur Folge, dass in unserem Projekt 50% der Kommentare nonsense sind, da jeder Konstruktor und jede private kommentiert werden muss. Bei exzessiver Nutzung von DI z.B. Construktor Injection führt das zu redundanten Kommentaren (einmal der Konstrukturparameter und dann das Field für den Service)…
Richtig ist: Kommentiert werden, sollten nur die Interfaces, Klassen und jene Methoden, die einer Kommentierung benötigen.
Wenn man CleanCode, SolidCode u.s.w. gelesen hat, stellt man fest, das darüber breiter konsens besteht. Ich würde sogar soweit gehen, zu behaupten, das Code der kommentiert werden muss, nicht aussreichend durchdacht entwickelt wurde (gerade inline kommentare zeugen von kompliziertem Code – meist Spaghetticode).
Guter Quellcode ist weitestgehends selbsterklärend. Dabei sollte aber nicht nur die Verschachtelungstiefe u.Ä. der Methoden betrachtet werden. Vielmehr kommt es auf eine passende Kohärenz und Kohäsion an. D.h. semantisch extrahierbare Bausteine in je nach Bedarf ein einzelne Klassen oder granularer in private Methoden auslagern, die einen, maximal zwei Parameter besitzen. Die Parameterlisten können dann sinnvollerweise kommentiert werden, was gerade in Zeiten von Intellisense zu empfehlen ist.
Allgemein gilt: Ist der Code sauber formuliert und grundlegende Qualitätskriterien sind eingehalten (Naming, Methoden/Klassengrößen, Single-Responsible Prinzip, Struktur, Parameteranzahl, Abhängigkeiten allgemein u.s.w.), ist eine Kommentierung nur selten notwendg.
Grüße
Holger
Christina
10. July 2012
Ich würde meinerseits nur öffentliche Methoden kommentieren, die aber vollständig, d.h. mit Angabe der eventuell ausgelösten Exceptions. Sonst sehe ich das genauso wie ihr: Kommentare sind ein smell
Johannes
10. July 2012
Hi Robert, ich hatte dazu vor ein paar Wochen auch was geschrieben
https://empathic.herokuapp.com/comments
Gruß
Johannes
Jim Martens
10. July 2012
Ich denke, dass man hier zwischen zwei Arten von Kommentaren unterscheiden muss. Die API-Kommentierung hat zum Zweck den Nutzer nach Schnittstelle entwickeln zu lassen, ohne dass er in den Sourcecode schauen muss (bei Bibliotheken; v.a. bei kompilierten Sprachen wo Sourcecode meist nicht zugänglich ist). Dort muss dann eine kurze Zusammenfassung stehen, was der Code macht, welche Parameter übergeben werden müssen, was zurückgegeben wird und ob etwaige Exceptions ausgelöst werden können. Wenn ja, wann und wie?
Diese Art von Kommentaren sind es auch, die dann bei IntelliSense oder ähnlichen Methoden von der IDE nützlich angezeigt werden können. Solche Kommentare sollten bei jeder Klasse, Objekt- und Klassenvariablen und allen non-private Methoden stehen.
Dann gibt es noch die Programmierguidelinekommentare, die für andere Programmierer gedacht sind, die den Code weiterentwickeln sollen. Bei diesen Kommentaren kommt es darauf an zu sagen, warum was wie gemacht wurde, welchen Zweck es fachlich erfüllt, etc. Gerade in kleinen Projekten hat man aber oft nicht Zeit für beides, sodass man sich auf die API-Kommentare konzentrieren sollte.
Carsten
10. July 2012
Schon zur Selbsthilfe hab ich mir irgendwann angwöhnt immer dann zu kommentieren, wenn ungewöhnliche Schritte gemacht werden, die auf dem ersten Blick nicht nachvollziehbar sind oder überflüssig erscheinen.
In einem halben Jahr hat man doch eh wieder vergessen, was das Besondere an dieser einen Stelle war, weshalb man das so und nicht anders gelöst hat.
SquadWuschel
11. July 2012
Hallo,
naja ich stehe auf Kommentare vor allem in den Funktionen selbst, hier muss ich quasi keinen Code lesen sondern nur anhand der Kommentare wissen was passiert. So kommentiere ich zumindest meine Projekte. Was Konstruktor Kommentierung und Properties und co angeht muss ich auch sagen hier wird nur da kommentiert wo es wichtig ist, z.B. bei Klassen schreibe ich meist kurz darüber für was diese “zuständig” ist. Ansonsten kann ich es nicht leiden wenn ich Klassen sehe die 5000 Zeilen lang sind und evtl. 3 Zeilen an Kommentaren enthalten.
Kommentare sind mit das wichtigste Mittel um z.b. mir oder anderen Leuten das Zurechtfinden in Code auch nach Monaten wieder so einfach wie möglich zu gestalten. Es muss drin stehen warum ich was gemacht habe und auf was ich evtl. noch zu achten habe.
Wenn man dauerhaft Kommentare einfügt im Code, dann geht es auch ins Blut über diese direkt zu korrigieren wenn man codeänderungen vornimmt. Wer dem wiederspricht, der kommentiert noch nicht genug
bei mir ist Code zu Kommentar rund 2:1 im Verhältnis.
mfg SquadWuschel