| 

.NET C# Java Javascript Exception

1
Sollte man wirklich jede Methode dokumentieren? Selbst Setter/Getter und Konstruktoren? Auch private Methoden?


Nehmen wir an wir hätten die Klasse "Person" und deren Methode "getLastName()". Ist doch ziemlich offensichlich was diese tut...
News:
20.03.2010
ermin 1,3k 2 7
ermin 1,3k 2 7
3 Antworten
2
Wenn man mit CodeGenerierungsTools arbeitet, um vielleicht eine technische Doku zu erstellen, macht es schon Sinn so viel wie möglich zu kommentieren, insbesondere um einfach mehr Semantik an den Konsumenten beispielsweise einer Serviceschnittstelle oder an einem Entwickler der die Methode verwenden soll, zu bringen.

Ich sehe auch einen Mehrwert darin, wenn man etwas Beispielcode, wie man denn eine (komplexe) Methode / Operation verwenden kann, mit einbringt.

Hier geht es auch darum, das du deinen Code - eben auch ein paar Monate später - schnell wieder rein findest und dann auch sogleich verstehst, wenn mal eine Änderung oder Erweiterung ansteht.
20.03.2010
Mario Priebe 6,0k 3 9
1
Idealerweise sollte man im Code möglichst wenig kommentieren müssen. Aus dem orangenen Grad des CleanCodeDeveloper (http://clean-code-developer.de/wiki/CcdOrangerGrad#SourceCodeKonventionen) geht hervor, dass man Kommentare durch bessere Namensgebung der Methoden, Variablen etc. vermeiden sollte. Bei deinem Beispiel ist ein Kommentar daher überflüssig. Natürlich kommt man manchmal nicht um Kommentare herum, z.B. wenn eine Klasse bzw. Funktion so viele Besonderheiten (z.B. nicht thread-safe) hat, dass sie nicht alle in den Namen passen.
Bei Klassen- und Methodennamen sollte man Javadoc-Kommentare (/** */) verwenden (zumindest in Java, ich weiß nicht, wie es in C# aussieht).
20.03.2010
clonejo 144 2 6
1
Um einen ehemaligen Kollegen zu zitieren:
Software = Code + Dokumentation

Code ist leider selten soo einfach, dass ein Methodenname eindeutig alle diese Dinge beschreiben kann:

  • Rückgabetyp (IDEs vereinfachen das bereits deutlich, aber manchmal reicht das allein nicht)
  • Wertebereiche des Rückgabetyps, maximale Zeichenlänge, bei Objekten mag es interessant sein dass diese sich in einem gewissen Zustand befinden wenn man sie erhält
  • Empfehlungen wofür die Funktion gedacht ist und wofür nicht - etwa ob diese Funktion besonders performant ist, oder ob sie es aus einem bestimmten Grund nicht ist und man andere Wege zum Ziel verfolgen sollte.
  • Beispielimplementierungen, bei aufwendigeren Klassen
  • Erwartete Parameter und deren Eingabegrößen, Wertebereiche, etc.
  • Arbeitest Du mit Polymorphismus, Threads, dynamischer Codegenerierung oder alls gleichzeitig? Hier wird es sehr schnell sehr kompliziert und man verbringt Stunden damit Code zu verstehen wenn er nicht dokumentiert ist.


Um auf Deine Frage zurückzukommen: Ein gewisses Augenmaß ist erforderlich um zu erkennen ob hier eine ausführliche Dokumentation hilfreich ist oder eine kurze ausreicht (wie in Deinem Beispiel).

Auf Dokumentation verzichten würde ich persönlich nur ungern, denn es gibt einen weiteren netten Effekt beim Schreiben von Dokumentation: Du denkst nochmal darüber nach was Deine Funktion eigentlich tun soll. Allein dieser Denkprozess sollte Dir helfen Deinen Code zu verbessern, da Du auf Ideen kommst, die Dir alleine beim Lösen eines konkreten Problems gar nicht in den Sinn kommen. (Das gleiche passiert noch viel besser beim Test-Driven-Development). Viele Funktionen habe ich durch das Schreiben von Beschreibungen automatisch hinterfragt und konnte diesen Code durchaus nochmal verbessern.

Und zu guter letzt hilfst Du Dir selbst und anderen auf einen Blick zu verstehen wie Deine Funktion zu benutzen ist. Stell Dir vor die Klassen und Methoden die Dir Java oder .NET zu Verfügung stellen wären nicht dokumentiert. Du würdest die erforderlichen Funktionen nicht finden (da Du nach nichts suchen kannst) und wenn Du es findest, würde Dir die konkrete Anleitung fehlen wofür bestimmte Dinge gedacht sind.

Insgesamt habe ich noch nie davon gehört, dass es ein Projekt gibt, bei dem zu viel Dokumentiert wurde. Meistens beschwert man sich immer über das Gegenteil, nämlich schlechte Dokumentation - daher, und aus obigen Gründen, würde ich im Zweifelsfall lieber zu viel als zu wenig machen.
21.03.2010
Vash 440 2 6
Wunderbar auf den Punkt gebracht, Vielen Dank dafür.
Mario Priebe 23.03.2010

Stelle deine .net-Frage jetzt!
TOP TECHNOLOGIES CONSULTING GmbH