Kategorien
Clean Code – Überflüssige Kommentare
Im Informatikstudium erfährt man in einem Fach das man auf „Softwareentwicklung“ verallgemeinern kann meistens wie wichtig es ist SÄMTLICHEN Quellcode zu dokumentieren. Als Grundgedanke ist das auch absolut erstrebenswert doch möchte ich hier nochmal die Frage aufwerfen wann zu viele bzw. falsche Kommentare mehr schaden als nutzen.
Nils hat sich vor längerer Zeit schon einmal mit Kommentaren direkt im Quellcode beschäftigt und damit wie man sie durch bessere Methodennamen vermeiden kann. Außerdem gib es im PHP-Magazin einen sehr schönen Artikel zum Kommentar-Smell.
Meine Argumentationsgrundlage soll hier „Zeit“ sein. Sourcecode wir öfter gelesen als geschrieben und sollte so geschrieben werden, dass er schnell erfassbar und verständlich ist. Deswegen einigen wir uns für Projekte auf Coding-Standards und nehmen uns – meistens/hoffentlich – Zeit dafür Methoden aussagekräftig zu benennen.
Etwas Beispielcode der gerne auch mal mit dem Satz „Ihr habt gesagt ich soll alles dokumentieren !“ einhergeht und mir physischen Schmerz bereitet.
<?php
class meineKlasse {
/**
* Konstruktur
*/
public function __construct() {
}
// ... Methoden der Klasse
}
Dieser Code ist auf mindestens zwei Ebenen verstörend.
Der Kommentar absolut überflüssig. Er beinhaltet keinerlei Information und hilft niemandem der auch nur ein kleiner bischen PHP kann weiter. Das Einzige das er erreicht ist, dass jeder der die Klasse öffnet ihn ggf. kurz überfliegt und damit Zeit verschwendet.
Wie wäre es mit „Erstellt eine Instanz von meineKlasse“ ?
Das wäre noch schlimmer, mehr Wörter, mehr Zeit, immer noch keine Information und beim umbenennen der Klasse müsste man ihn auch noch anpassen.
Ich finde hier kann man sich den kompletten DocBlock sparen. Wenn ihr euch in eurem Projekt darauf geeinigt habt, dass alles einen DocBlock hat, würde ich vorschlagen den einfach leer zu lassen. Wenn das auch nicht erlaubt ist würde ich sehr gerne von euch hören wieso und euch ggf. empfehlen diese Regel zu ändern. Es nützt nichts Entwickler damit zu beschäftigen Trivialitäten niederzuschreiben, es senkt meiner Erfahrung nach sogar die Qualität der restlichen Dokumentation wenn die Leute mit einer „muss irgendwas über alles schreiben damit der Code Sniffer zufrieden ist“ Mentalität an die Sache herangehen, ob bewusst oder unbewusst.
Der einfachste Weg hier die Problematik zu umgehen ist aber den Konstruktor einfach komplett zu löschen. Er erfüllt im Moment keine Funktion ! Er ist sogar mögliche Fehlerquelle da er den „parent“ Konstruktor nicht aufruft, etwas das automatisch geschieht wenn diese 5 Codezeilen gelöscht würden. Solche leeren Konstruktoren kommen meistens daher, dass sie in einem Klassentemplate existieren und an den Stellen an denen sie nicht gebraucht werden nicht gelöscht werden.
Also spart Zeit und erhöht die „Information pro Bildschirmseite“ wo es sinnvoll ist. Eurer zukünftiges Ich wird es euch danken.
Unnötige Kommentare habe ich schon zu oft gesehen. „Dies ist der Konstruktor“, „Daten aus Datenbank holen“ bei
$db->select();usw. usf.Danke für diesen Artikel. Den werde ich heute noch an ein paar Leute weiterleiten.
Dein Argument „Zeit“ finde ich sehr gut. Sehr schoener Ansatz.
Ich muss allerdings auch sagen das es eine Art Gegenveranstaltung zu deinem Fach „Softwareentwicklung“ gibt. Bei uns wird ein Semester nur ueber schoenen Quellcode/ Code-Smell geredet.
Hm ist ein schwieriges Thema. Kommentare wie der obige bringen wirklich wenig. Auf der anderen Seite bin ich immer dafür „public“-Methoden zu kommentieren, damit man die Unterstützung der IDE voll genießen kann und nicht bei jedem Methoden-Aufruf in die Klasse springen muss, um zu verstehen, was die ganz genau macht. Hier sind mE auch Trivialkommentare erlaubt.
Bei „private“-Methoden sehe ich das schon wieder etwas anders. Diese werden nur in der Klasse genutzt und somit ist der Kommentar hier möglicherweise nur dann notwendig, wenn er auch eine Mehrinformation bietet.
Also müsste man einen Sniff definieren, der auf public überprüft und dort immer einen Kommentar verlangt. Bei Konstruktoren nur dann, wenn es Eingabeparameter gibt. Geht man nach dem Pareto-Prinzip vor, dann erwartet man halt immer einen Kommentar – ich bin da recht unentschlossen was der beste Weg ist.
DocBlock Kommentare sind natuerlich dann sinnvoll, wenn man eine API Dokumentation aus seinem Code generieren will/muss.
Ansonsten gebe ich dir recht.
Dennoch fehlt mir ein wichtiges Argument naemlich das der Pflege von Kommentare. Ich habe schon unzaehlige Klassen gesehen, in denen ausreichend Kommentare vorhanden waren, die mir eigentlich schnell haetten weiterhelfen sollen. Nur waren sie oft nicht mehr mit dem Code zusammenhaengend, den sie beschrieben. Oder der beschriebene Code war bereits nicht mehr vorhanden. Kommentare altern halt.
Das liegt daran, dass Code sich im Laufe der Zeit aendert (Refactoring, neue Features, etc..) aber die dazugehoerenden Kommentare oft vergessen werden und anschliessend eher stoerend als hilfreich sind.
Solche leeren Konstruktoren zu verwenden, ist an sich schon nicht zu empfehlen. Da sie dann auch nicht existieren, hat sich die Problematik mit den Kommentaren dafür auch erledigt. Ansonsten halte ich überflüssige Kommentare allerdings auch für unnütz. Gerade das hier schon genannte Beispiel mit den Daten aus einer Datenbank ist so ein Dauerrenner, oder auch der Hinweis das jetzt etwas berechnet wird 🙂
Allerdings ist es manchmal auch nicht leicht, zu entscheiden, wann ist ein Kommentar angebracht, und wann ist der Code selbsterklärend. Für mich, als Programmierer ist er es im Moment, in dem ich ihn schreibe auf jeden Fall. Aber ist er es auch für anderen, oder für mich, in 20 Monaten?
Ansonsten verwende ich grundsätzlich DocBlock Kommentare, erstens wegen der IDE, zweites wegen der API-Doc Generierung und drittens weil es den Code auch zusätzlich strukturiert, wenn man sie sinnvoll verwendet.
Das Argument mit den “Informationen pro Bildschirmseite” halte ich seit der Erfindung des Code-Foldings für obsolete.
Ich finde dieses Beispiel nicht Aussagekräftig genug. Denn wer schreibt schon leere Methoden, mal abgesehen von abstrakten Methoden, in seinen Quellcode. Diese dann auch noch für eine Diskussion über die Dokumentation der gleichen her zu nehmen finde ich am Thema vorbei.
Ich denke sobald eine Methode auch eine Funktion hat kann man diese beschreiben. Sicher gibt es auch Methoden die nur Variablen setzen oder zurück geben. Aber ich finde selbst diese sollte man mit einem kleinen Kommentar versehen. Selbst wenn es nur „Setter for the xyz property.“ oder „The class constructor.“ ist.
+
Dokumentation aus Quellcode erzeugen
Konsistenz
Bessere Lesbarkeit durch einheitliches Bild
–
Mehr Aufwand durch das schreiben der Kommentare
Wie sieht es eigentlich dann mit Interface Methoden oder abstrakten Methoden aus? Sollte man diese dann auch nicht dokumentieren?
Software documentation is like sex: when it is good, it is very, very
good; and when it is bad, it is better than nothing.(Anonymous)
Ich kann euch nur entschieden widersprechen. Natürlich ist es sinnvoll schlechte Kommentare durch gute zu ersetzen. Aber der Ansatz schlechte Kommentare lieber gleich wegzulassen führt nie zu guten Kommentaren!
Wenn schlechte Kommentare Schmerz verursachen beim Leser, dann ist das erst einmal ein gutes Zeichen. Jedoch muss der Weg den Schmerz zu beseitigen der zu guten Kommentaren sein und nicht zu keinen Kommentaren.
Die Annahme der Sourcecode wäre selbsterklärend trifft der Entwickler (!sic) meist direkt (!sic) nach der Implementierung, wo wir beim zweiten großen Problem eures Ansatzes wären.
Ich kann nur dem von mir zitierten Ansatz unterstützen und wenn euch schlechte Kommentare stören, dann macht sie besser!
wer sagte noch gleich… „It was hard to wrote, it must be hard to understand“ 🙂
@Martin: Ich mag deinen Lehrsatz 🙂
@Volker: Danke für den Artikel
Also ich bin auch Martins Meinung. Ich bin auch froh, wenn meine Entwickler überhaupt soweit sind, dass sie ihren Code ordentlich mit Doc-Blocks versehen. Triviale Kommentare sind da erst mal besser als keine. Weil man kann ja nicht nur Code refactoren, sondern auch Kommentare. Das ist zwar in den meisten Projekten Luxus, aber nach der Pfadfinder-Regel (hinterlasse den Code besser als du ihn vorgefunden hast) kann man solche Kommentare immer Stück für Stück etwas aussagekräftiger machen.
Und es ist einfacher seinen Entwicklern klar zu machen: Überall ein Doc-Block und das Build-System meckert wenn es nicht so ist, als das man anfängt zu erklären hier ja, da nein und das.. naja das ist Auslegungssache… Das führt dazu, dass Entwickler eine Ausrede für ihre Faulheit haben: Ich dachte das wäre trivial. Weil Trivial ist auch immer auslegungssache.
Auch Kommentare der Art: „Datenbankverbindung holen“ sind nicht immer böse.
Weil wenn ich eine kompliziertere Methode implementiere schreibe ich zuerst in Kommentaren hin was die Methode Stück für Stück machen soll. Und fülle dahinter den Code. So muss man später nur die Kommentarzeilen überfliegen und weiß was in der Methode passiert. Das ist dann eben doch schneller als sich Stück für Stück die Codeblöcke anzuschauen.
Es geht beim Kommentieren für mich primär um drei Dinge:
1. API Docs erzeugen
2. IDEs bedienen
3. Implizites explizit machen
Beispiel:
/**
* Calculates the Body Mass Index (BMI)
*
* @link http://en.wikipedia.org/wiki/Body_mass_index
* @param Integer $weightInKg Body Weight in kilograms
* @param Integer $heightInCm Body Height in centimeters
* @return Float
*/
function getBodyMassIndex($weightInKg, $heightInCm)
{
return $weightInKg / pow($heightInCm/100, 2);
}
Ich behaupte jetzt einfach mal, dass diese Funktion auch ohne die Kommentare für jedermann schnell zu verstehen ist. Funktionsname und Argumente sind sprechend und der Rumpf bei weitem kein Hexenwerk. Dass cm und kg als Zahlwerte angegeben werden, weiß jeder, der weiß was cm und kg sind. Ebenso, dass der zurückgegebene Wert auch ein Zahlenwert sein wird, wahrscheinlich eine Kommazahl.
Sollte man den DocBlock dann weg lassen? Nein, sollte man nicht. Denn wie auch beim Konstruktor ist auch hier die Grundlage: Vorwissen. Ich muss wissen, dass kg und cm Zahlen sind. Meine IDE weiß das zum Beispiel nicht. Sie kann auch nicht ableiten, dass eine Division meistens einen Float zurück gibt. Also muss ich es ihr sagen. Damit sind zumindest schon einmal die Annotations nicht überflüssig.
Und der Kommentar? Der ist an sich nicht viel anders als „Erzeugt eine Instanz von meineKlasse“. Aber wäre es besser, wenn dort stehen würde, was im Rumpf passiert? Wenn ich nicht weiß, was der BMI ist, nutzt mir auch das nichts. Erst die Link Annotation hilft mir da weiter, denn da steht, was der BMI ist. Der Vollständigkeit halber (und um 1. zu genügen) schreibe ich trotzdem noch einen vollständigen Satz dort hin. Ich persönlich lese natürliche Sprachen immer noch schneller als Code und als Entwickler interessiert mich oft auch nicht, was im Rumpf passiert, sondern nur das Interface.
Diese Kommentare, so trivial sie auch aussehen, werden vom Documentator gelesen und ergeben – sofern man sie pflegt – eine komplett beschriebene API, die in sich konsistent ist. Aus diesem Grund empfehle ich Sie nicht wegzulassen.
Die anderen Argumente haben weiterhin ihre fudierte Berechtigung. Falsch dokumentierter Code ist schlimmer als nicht dokumentierter Code und mit aussagekräftigen Bezeichnungen kann man sich viel Mehrdeutigkeit ersparen.
Die Beschreibung von Methoden und Membern gliedern den Quelltext in sich, und machen des Lesen für den Programmierer leichter. Das Auge muss nicht zwischen den Zeilen springen und die abschließende Klammer suchen.
Vielen Dank für alle eure Kommentare ! Sehr spannende Antworten dabei 🙂 Freut mich.
Um das ggf. noch klar zustellen: Ich will in keiner weiße sagen das man keine PhpDoc Kommentare schreiben sollte. Solange es kein komplettes Typehinting für PHP gibt ist @param und @return meiner Meinung nach absolut unverzichtbar ! Wenn ich von Kommentaren gesprochen habe meinte ich im Artikel nur „Fließtext“.
Um vielleicht nochmal ein Beispiel anzuführen nehme ich hier mal Arnos Beispiel aus den Kommentaren und schreibe den Code etwas um.
/**
* @link http://en.wikipedia.org/wiki/Body_mass_index
* @param int $personsWeightInKilograms
* @param int $personsHeightInCentimeters
* @return float
*/
function calculateBodyMassIndex($personsWeightInKilograms, $personsWeightInKilograms)
{
return $personsWeightInKilograms / pow($personsWeightInKilograms / 100, 2);
}
(Wenn das ganze Teil einer „Person“ (o.ä.) Klasse ist würde ich das „persons“ im Variablennamen auf jedenfall weglassen, so kann man sich streiten, im zweifel verbose 😉 )
Gerade hier einen kürzeren Variablennamen mit „kg“ zu wählen nur um in der Doku das Kürzel auszuschreiben erscheint mir nicht nützlich. Aber es gibt Programmierer und Teams die lieber kurze Namen haben weil sie die Doku sowieso in der IDE permanent parat haben.
Das Argument „wir (das Team) finden das alle gut und wollen das so machen und es funktioniert gut“ schlägt meiner meinung nach sowieso alles andere.
Nochmal danke fürs Feedback !
Auch wir haben intern immer wieder Diskussionen, was jetzt nun dokumentiert werden soll und was nicht. Wir haben uns auf folgendes geeinigt:
Public: Immer phpdoc + Beschreibung
Private: parameter / return values / Beschreibung falls Methode nicht klar ist
Hier noch meine Buchrezension zu Clean Code:
http://daraff.ch/2010/03/buchrezension-clean-code-von-robert-c-martin/
Hier vielleicht noch ein interessanter Artikel, wo ich analysiert habe, das Dokumentation Geld spart:
http://daraff.ch/2010/02/dokumentation-spart-geld/
Hallo,
die letzten 3 Antworten treffen für mich auch zu. Martin Fowler im Buch Clean Code beschreibt das Thema Kommentare im Fließtext ungefähr so:
„Wenn es nötig wird eine Logik zu kommentieren damit sie jemand versteht, ist es in den meisten Fällen auch nötig den Code so zu refactoren das der Code für sich selbst sprechen kann.“
Das habe ich mir zu eigen gemacht und finde die BMI Version von Volker ansprechender. Kommentare wie „Calculates the Body Mass Index (BMI)“ sollten sich aus dem Quelltext ergeben.
Gruss
Sebastian
Ach, ich wäre ja schon froh, wenn die Entwickler überhaupt dokumentieren würden was sie machen.
Stattdessen bekomme ich immer wieder sowas zu sehen:
function holedaten() { … }
function rechneNeu() { … }
function losjetzt() { … }
function losjetzt2() { … }
$old1 = „“;
$old2 = „“;
$newA = 0;
$newA2 = 1;
Ernsthaft. Da freue ich mich über jeden Kommentar, so unsinnig er auch sei.
@Nils schlechtes Beispiel mit dem Konstruktor. Die Beschriftung „Konstruktor“ für die Funktion „__construct“ ist nicht überflüssig. Denn in der API-Doku taucht der Funktionsname nicht mehr als Titel auf. Die Redundanz ist also sogar notwendig.
Der PEAR Coding-Standard fordert im übrigen Doc-Blöcke und (redundante) Annotations als Pflichtangaben (in einer vorgegebenen Reihenfolge). Du kannst dich gern mit den Jungs streiten … es wird dir nur nichts bringen. Das ist historisch so gewachsen. Da könntest du auch gleich versuchen, denen die VIM-Kommentarblöcke auszureden. Viel Glück! 😉
@Sebastian das sehe ich nicht so wie Fowler. In der API-Dokumentation ist der Quellcode nicht enthalten. Der Inhalt kann sich also nicht aus diesem ergeben. Die Kommentierung muss also erläutern, was im Quellcode passiert.
(Zur Pflege der API-Doku gehört es IMHO irrelevante interne Klassen/Funktionen mit @ignore aus der Doku zu entfernen, um den Entwickler nicht unnötig damit zu belasten.)
Nicht alles ist so klar wie es scheint:
public function setWidth($width) { … }
Breite von was?
Innendurchmesser oder Außendurchmesser?
Einheit: Meter, Kilometer, Meilen, …?
Rückgabewert?
Erwarteter Datentyp: int oder float?
Werden Exceptions geworfen?
Grenzwerte? 0 erlaubt? -1 erlaubt? 32.000 erlaubt?
Kann ich NULL übergeben, um den Wert zurückzusetzen?
Angenommen auf Grundlage des undokumentierten Codes berechnet ein Azubi in einem externen Programm einen Frachtkostenzuschlag für einen Kunden … in der falschen Maßeinheit. Dann wird’s teuer.
Schönes Beispiel für gute Dokumentation:
/**
* overwritten constructor
*
* @ignore
*/
public function __construct()
{
// intentionally left blank
}
Sagt mir: 1) der Entwickler hat nicht vergessen, den Konstruktor zu implementieren – es war Absicht. 2) Die Basisklasse hat hier etwas getan hat, was unerwünscht ist. 3) @ignore steuert PHPDocumentor (nicht relevant für API-Doku).
Reflections-API: verwendet Annotations.
Entwurfsmuster als Annotations dokumentiert, erlauben bessere statische Code-Analyse (@Nils wäre das nicht was für dich?).
IDEs mögen Annotations und belohnen dies z.T. mit besserer Autovervollständigung.
Zitat Yukihiro Matsumoto: Convention over Documentation. Einheitliche Namensgebung, klare Konventionen für die Dokumentation. Stereotypen verwenden und einheitlich kennzeichnen. Einheitliches Vokabular.
Beispiele:
Suffix „Exception“ für von Exception abgeleitete Klassen.
Ableitungshierarchie AbstractDataAdapter <- DatabaseAdapter <- MediaDatabaseAdapter. Die Klassenhierarchie und das Entwurfsmuster ergeben sich fast schon aus der Namensgebung.
Singular getFoo() liefert Objekt/skalaren Wert Plural getFoos() liefert immer ein Array.
@Volker Gutes Beispiel. Allerdings würde sich CodeSniffer über die @param Annotations beschweren: da fehlt jeweils ein Kommentar.
Statt:
@param int $personsWeightInKilograms
Besser so:
@param int $weight person's weight in kilograms
In der API-Doku wird daraus nämlich eine Tabelle mit 3 Spalten: Type, Name, Description.
Also ich hab mir grundsätzlich angewöhnt, nicht das „Wie“, sondern das „Was“ zu kommentieren. Soll heißen: Übergabe-Parameter z.B. zu dokumentieren halte ich sinnvoll, jeden kleinen Fatz zu erklären wiederrum nicht, da man wohl davon ausgehen kann/sollte, daß andere Etwickler sehr wohl Code lesen und verstehen können bzw. sollten, wenn es denn nötig ist.
Und Sachen wie „das ist der Konstruktor blabla“ sind natürlich eh Quatsch.
Dokumentationen gehören meiner Meinung nur in Interfaces und Abstrakte Klassen. Und wenn eine Klasse erweitert wird sollte die Erweiterung dokumentiert werden.
Ich stehe auf dem Standpunkt, daß guter Code – bis auf Ausnahmen – nicht kommentiert werden muß.
Ausnahmen sind für mich z.B. die hier schon häufiger angesprochenen phpdoc-Kommentare. Und ggf. Kommentare, die nicht erklären *was* ich mache, sondern *warum* ich etwas mache.
Im Beispiel von Tom würde ich vielleicht sogar mehr Kommentar schreiben:
public function __construct()
{
// intentionally left blank to avoid execution of parent’s constructor, because …
}
Auch für TODOs sind Kommentare natürlich sehr sinnvoll.
Aber ansonsten gehe ich lieber nach dem „don’t repeat yourself“-Motto vor und benenne meine Klassen, Methoden und Variablen so, daß ein einigermaßen erfahrener Entwickler den Code einfach lesen und verstehen kann.
Ich dokumentier nur spärlich, achte dafür auf gut gewählte Funktionsnamen und Parameternamen. Eine IDE nutz ich nich, daher muss ich auch nicht jede Funktion kommentieren, um den vollen Funktionsumfang der IDE ausspielen zu können.
hmm. ist mir zu hoch…
php funktioniert doch intuitiv?
Günther
Folgender Code ist Teil einer If-Orgie, welche zu einer Funktion gehört, welche eigentlich nur den URI ermittelt:
[code]
// …
if (isset($_SERVER[‚HTTP_X_REWRITE_URL‘]))
{
// check this first so IIS will catch
$requestUri = $_SERVER[‚HTTP_X_REWRITE_URL‘];
}
elseif (isset($_SERVER[‚REQUEST_URI‘]))
{
$requestUri = $_SERVER[‚REQUEST_URI‘];
}
elseif (isset($_SERVER[‚ORIG_PATH_INFO‘]))
{
// IIS 5.0, PHP as CGI
$requestUri = $_SERVER[‚ORIG_PATH_INFO‘];
}
// …
[/code]
Die Funktion selber ist klein, der Funktionsname (bspw. „getUri()“) spricht für sich.
Manch einer wird hier der Meinung sein, diese Kommentare seien unnötig. Ich nicht:
Wenn ich die Funktion jetzt baue, informiere ich mich über die ganzen $_SERVER-Variablen.
Ich beschäftige mich womöglich was Direktiven wie „FcgidFixPathinfo“ oder „cgi.fix_pathinfo“.
Wenn ich die Funktion aber in ein paar Monaten noch einmal betrachte, oder gar ein Kollege, welcher sich noch nie im Detail mit URI auseiander gesetzt hat (OT: Hand auf Herz, wie vielen sind hier die unterschiedlichen Möglichkeiten alle bekannt? In der Regel hat man nur schon gelernt, dass $_SERVER[‚PHP_SELF‘] keine gute Idee ist, aber das war es), dann helfen einem solche kleinen Kommentare enorm wie ich finde.
Ich setze bspw. auch gerne bei regulären Ausdrücken einen kleinen Kommentar der beschreibt, was der Ausdruck macht. Auch dies würde sich aus dem Kontext ergeben.
P.s.: Ordentliche PHPDoc-Blöcke gehören meiner Meinung zu einem guten Stil – ohne wenn und aber (wer hier ernsthaft Gründe findet, auf PHPDoc-Blöcke verzichten zu können, hat imho noch nie im Team gearbeitet, kein Projekt über längere Zeit mit Unterbrechungen geführt… oder einfach keinen guten Stil :O)).
@Igor:
> Manch einer wird hier der Meinung sein,
> diese Kommentare seien unnötig. Ich nicht:
Ich auch nicht. Du schreibst ja auch, *warum* Du etwas machst („check this first so IIS will catch“) und nicht, *was* Du machst (z.B. „get request uri here“ oder „get request uri from $_SERVER var“ o.ä.).
Gruß,
Klaus
> P.s.: Ordentliche PHPDoc-Blöcke gehören meiner Meinung
> zu einem guten Stil – ohne wenn und aber
Die wären bei deiner Beispielfunktion aber völlig unnötig.
Was die Funktion macht, erkennst du wunderbar am Namen (getUri). Das sie keine Parameter erwartet siehst du auf dem ersten Blick. Da die Funktion ein Uri zurückgiebt, liegt es nahe, dass das ein String sein wird. Wofür das ganze nochmal detailiert dokumentieren und den Source 4 Zeilen länger machen?
@ fchriis:
> Die wären bei deiner Beispielfunktion aber völlig unnötig.
> Was die Funktion macht, erkennst du wunderbar am Namen (getUri).
> Das sie keine Parameter erwartet siehst du auf dem ersten Blick.
> Da die Funktion ein Uri zurückgiebt, liegt es nahe, dass das ein String sein wird.
Es mag manche Funktionen geben, wo sich aus Namen/Zusammenhang alles andere eigentlich ergeben sollte, ja. Aber genau das ist es, was in meinen Augen „Stil“ aus macht:
Ein Gentleman hält *jeder* Frau die Tür auf. Unabhängig davon ob er sie scharf findet oder nicht.
Insofern sollte man einfach immer einen PHPDoc-Block setzen. Es kostet wirklich keine Zeit. Hilft aber bei Leuten mit IDEs ungemein und sollte irgendwann einmal eine Dritte Person über den Code schauen, was man sich bei der Programmierung nie hat erträumen können, hilft es auch ihm.
Wächst der Code und man verwendet ihn plötzlich in einer API, wofür man gerne eine Dokumentation erstellen möchte, hat man sich gleich Arbeit gespart.
Nochmal:
Wer mit mir ernsthaft darüber diskutieren will, ob ein PHPDoc überflüssig ist oder nicht, der hat in meinen Augen noch *nie* im Team oder länger als 6 Monate an einem Projekt gearbeitet. In der Zeit, wo man sich Gründe überlegt, darauf zu verzichten, hat man schon 10 Klassen dokumentiert 😉
Ich will da auch niemandem zu nahe treten, aber wer wirklich jemals professionell entwickelt, dem wird u.a. bekannt sein, dass man in der Entwurfsphase oft nackte Gerüste bestehend aus dem Funktionsrumpf + PHPDoc baut, bevor irgendetwas implementiert wird.
Ein schönes aktuelles Beispiel:
http://zendframework.com/wiki/display/ZFPROP/Zend+Cache+2.0+-+Marc+Bennewitz
Das ist professionell. 🙂
@klg: So meinte ich das eigentlich auch – hab mich in meinem vorherigen Kommentar etwas blöd ausgedrückt…
Das obige Beispiel ist absurd und es ist vollkommen unklar, wozu solche Beispiele dienen sollen.
Kommentare sind eigentlich dazu da, um längeren Code (jetzt höre ich es kommen – man muss kürzen, in Methode aufteilen, etc. pp. …) in seinem Ablauf, und weniger nicht in seiner Struktur, zu dokumentieren. Zusätzlich sind Kommentare die einzige Möglichkeit, auf bestimmte Umstände hinzuweisen, die bei der Code-Modifikation bzw. Erweiterung zu berücksichtigen müssen.
Kurz um – Kommentare sind als Dokumentation zu verstehen.
Stellen Sie sich das mal anders vor – ein Ingenieur entwickelt einen Motor und schreibt ein Steuerungsprogramm für den Roboter. Auf die Nachfrage, wo ist die Dokumentation zum Motor, sagt er „ihr könnt ja alles ausmessen und wenn ihr es ändern wollt, ändert einfach Steuerprogramm für den Roboter, für welches ja selbstverständlich auch keine Dokumentation vorliegt – ihr könnt ja Quelltext auch lesen“.
Jedes dritte größere Softwareprojekt ohne saubere Dokumentation inkl. Inlinekommntare mit Laufzeit von über 5 Jahren wurde gegen die Wand gefahren bzw. müsste von neuen Entwicklern neu geschrieben sein, weil altes Code nicht mehr verständlich war.