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?
