Kategorien
Was wäre wenn: einfach mal auf deutsch
Die Überschrift klingt doch schon fast wie eine neue Reihe. Und genau das soll es auch sein, ein paar Ideen hab ich schon. Aber erklären wir erst mal, was ich hier so ansprechen will. Es gibt so so ein paar Gesetze in der Softwareentwicklung, die man einfach nicht in Frage stellt. Aber warum eigentlich nicht? Weil wir es schon immer so gemacht haben? Das Argument lasse ich nie gelten, warum gerade hier. Hier möchte ich solche Punkte ansprechen und einfach mal für mich aufklären, was passiert wenn man es einfach mal anders macht. Vielleicht geht ja die Welt unter, aber vielleicht eben auch nicht. Inspiriert wurde ich übrigens von Mike (auch wenn er es vielleicht gar nicht mehr weiß) , also Hooray for Mike.
Wenn wir in der Überschrift weiterlesen, dann kommt man vielleicht schon darauf, was ich ansprechen will. In der Programmierung ist es eisernes Gesetz alle Kommentare auf Englisch zu schreiben. Aber warum eigentlich? Jetzt stellen wir uns mal vor, ab morgen wären alle unsere internen Projekte nur noch auf Deutsch kommentiert. Wir wachen also auf und alles ist anders. Aber was würde sich ändern für meinen Programmieralltag? Ich befürchte ja nichts! Naja vielleicht würde ich meine Kommentare schneller schreiben. Mein Englisch ist gut, aber mein Deutsch ist besser. Ich kann mich in meiner Muttersprache so ausdrücken, dass es kaum zu Missverständnissen kommen kann, ob das immer in der Fremdsprache gelingt sei dahingestellt. Zumindest habe ich schon Kommentare gelesen, die echt fürn A**** waren.
So jetzt zu den Nachteilen. Wir schreiben ja auch Englisch, da es sein kann, dass internationale Teams den Source Code verwenden und dann macht es natürlich Sinn. Ist bei mir aber nicht so. Alle internen Programme, die ich für meinen Beruf schreibe sind wirklich nur für den internen Gebrauch und ich möchte mal behaupten, dass bei allen 30 Entwicklern das Deutsch besser ist als ihr Englisch.
Natürlich würde ich mich nie trauen, diese heilige Regeln zu brechen und mal die anderen Entwickler zu fragen, ob wir das ab jetzt in Deutsch machen wollen, aber eigentlich sollte man das machen. Bei Funktions- und Klassennamen würde ich das ein wenig anders sehen. Da gibt es Standards, sowas wie get, set, store, etc, nach denen man sucht, wenn man bestimmte Funktionalitäten nutzen will. Für Kommentare kenne ich sowas nicht, zumindest halte ich mich dort an keine Regeln.
So jetzt die Frage an euch, was würde bei euch passieren, wenn ihr eure Kommentare auf Deutsch schreiben würden?
Bei uns im Team haben wir definiert, dass Kommentare auf deutsch geschrieben werden. Genau wegen den Punkten, die du erwähnt hast.
1. Ausdruckskraft und Verständlichkeit in der Muttersprache ist besser
2. Chance, dass ein ausländisches Team mitarbeiten wird wird, ist seeeeeehr gering.
Es spricht meiner Meinung nach grundsätzlich nichts dagegen. Wenn die Kommentare dadurch besser werden, warum nicht? Bei Software die mit Sicherheit nicht samt Quellcode veröffentlicht wird habe ich kein Problem damit, wenn alles auf Deutsch ist.
*und dann stellte die Firma sowohl einen Bayer als auch nen Berliner ein.*
Woroauf ich hinaus will. Im englischen gibt es im grunde 2 Dialekte, den amerikanischen und den englischen. Und die unterscheiden sich so gering, dass es eigentlich kaum auffällt wenn man nicht gerade in einem der beiden Länder lebt. Es gibt zwar auch dort umgangssprache, aber darin wird wohl kaum jemand Codekommentare schreiben.
Wie ist das mit Deutsch in Deutschland? Du hast potenziell in jedem Bundesland einen anderen Dialekt und viele Wörter die unterschiedlich sind. Es gibt sogar Regionen in Deutschland, die sprechen ein Deutsch, was andere für eine Fremdsprache halten würden.
Es sollte also zumindest festgelegt werden, auf was für ein Deutsch man sich einigt.
Ist das bei euch nun (ich nehme zumindest an, dass ihr dann in Hochdeutsch schreibt) Hochdeutsch weil es so festgelegt wurde, oder ist es Hochdeutsch, weil das zufällig der größte gemeinsame sprachliche Nenner ist?
Wenn du schon get,set und store anspricht was ist dann mit @return und @var usw.. ? Also PHPDoc?
@Flyingmana: Hast du schon einmal eine bayrische Zeitung gelesen? Alles in Hochdeutsch. 😉 Die Dialekte hierzulande äußern sich nur in der Sprache, nicht der Schrift. Insofern sollte das kein Problem darstellen. Nur lokal vorkommende Begriffe dürften zudem in Kommentaren eine Seltenheit darstellen – und IT-Fachbegriffe wiederum deutschlandweit identisch sein.
@flyingmama
wie sieht denn dialekt geschrieben aus?
ich habe noch niemals einen unterschied zwischen einem halbwegs vernuenftigen geschrieben kommentar aus bayern oder hamburg sehen koennen.
ein jo mei oder spitzen stein wird mal wohl kaum jemals in einem kommentar zu lesen bekommen?
Hmm, stellt sich doch grundsätzlich mal die alte Frage wieviel Kommentare denn wirklich in einem Sourcecode stehen. Bin ein großer Freund von Clean-Code und eigentlich der Meinung, dass gut geschriebener Quellcode selbsterklärend sein sollte 🙂
Selbst wenn man jetzt verfechter von Kommentaren ist: Wir arbeiten doch in einem Umfeld, in dem es von englischsprachigen Begriffen nur so wimmelt, da ist doch die hälfte aller Wörter so oder so auf englisch 😉
Also ich persönlich bevorzuge englische Kommentare, ich schreibe ja keine Prosa und halbseitigen Texte damit…
Das hat sich ja ursprünglich deswegen eingebürgert, weil man immer eine eventuelle Zusammenarbeit mit externen Dienstleistern im Hinterkopf hat…
Was für open source Projekte natürlich nicht funktionieren kann ist in der Firma für mich ist das Alltag: Konsequent umgesetztes Denglish.
Als das Projekt vor 10 Jahren begonnen wurde waren ein paar der Entwickler ob ihrer Russischen Abstammung einfach nicht flüssig in Englisch und so ist entschieden worden das alles auf deutsch gemacht wird.
Die Geschäftslogik ist damit richtig schön umsetzbar und alle Klassennamen sind frei wählbar, ganz ohne namespaces 😉
Zu der Liste der „doch englischen“ Wörter fallen mir gerade spontan ein: „get, set, fetch, prepare, draw, output, factory, import, export, collection, settings, config, session, plot, style, init, create“ und noch so ca. 25 mehr die immer mal wieder im Code auftauchen.
Im großen und ganzen sehe ich keine großen Vorteile, beim Kommentieren geht die möglicherweise gesparte zeit auch wieder damit drauf das irgendwelche feststehenden englischen Begriffe entweder übersetzt werden oder man lustige denglishe adjektive erfindet um halbwegs lesbare Sätze zu bekommen.
Ein anderes Problem ist die Konsistenz: Hat man eine einsprachige Codebase kann man halbwegs mit Spellcheckern arbeiten (wenn man das will) und es gäbe nur _eine_ richtige Schreibweise für die meisten Wörter.
Ich finde die Idee gut Kommentare in Deutsch zu schreiben, finde aber auch gut Klassen und Methoden in Deutsch zu schreiben. Warum nicht getBenutzerName? Get und Set sind einfach Prefixes.
Lieber selbsterklärenden Code als gute Kommentare zu schwer verständlichem Code. Wenn ich anfange zu Kommentieren, habe ich bereits fast verloren.
Einen Vorteil hat die englische Sprache schon: sie ist kürzer. Das hilft beim Querlesen. Und man denkt einheitlich. Vorallem PHP ist ans Englische angelehnt. Kommentare in anderen Sprachen stören den Lesefluß, weil man umdenken muss.
Ein anderer Vorteil wäre, dass sich Deutsche gerne umständlich ausdrücken. Bei mir persönlich merke ich, dass ich beim englischen einfachere Sätze schreibe, und versuche komplizierte Dinge einfach auszudrücken. Mit ein wenig Übung geht dies auch wunderbar. Wenn man merkt, dass der Kommentar zu schwierig ist, sollte man sich seine Methode/Funktion nochmal vornehmen und lieber hier investieren, als in einen guten Kommentar.
Ist das mit den regionalen Unterschieden in Deutschland tatsächlich so gering im schriftlichen?
Ich persönlich kenne nur das Berlinische im schriftlichen, und haben damit auch schon sehr viele die hier aufgewachsen sind Probleme, da in Schule und Zeitung nur noch Hochdeutsch verwendet wird.
Ansonsten wäre es das Thema betreffend praktisch, wenn PHP bald auch utf8 in Klassen und Funktionsnamen ermöglichen würde. Schließlich gehören Umlaute zur deutschen Sprache, auch wenn man sie leicht umgehen kann.
Ja deutsche Bezeichnungen für Klassen und Methoden hat schon mein alter Java Lehrer propagiert. Die Gefahr in Konflikte zu kommen ist deutlich geringer.
Unsere rumänischen Kollegen könnten dann leider sehr wenig mit den deutschen Kommentaren anfangen. Kommt für uns also nicht in Frage.
Ich kommentier nur auf Deutsch, da die Kommentare eh nur für mich und ab und zu einige (deutsche) Kollegen gedacht sind. Warum sollte ich da alles extra übersetzen?
Der Code ansich ist aber immer englisch. Einen Mischmasch (interne PHP-Funktionen englisch, eigene deutsch) finde ich einfach nicht gut. Vorallem haben sich manche Funktionsnamen (wie das schon genannte get und set) einfach eingebürgert.
OpenSource-Projekte, bzw Programmcode der wirklich für alle gedacht ist würde ich allerdings auch auf Englisch kommentieren. Kommt wie so oft auf die Zielgruppe an. 🙂
@Stephan: Das ist natürlich doof. Wenn wir „outsourcen“, dann machen wir das über Bodyleasing, dass heißt, wir holen uns die Leute ins Haus. Meistens sind es dann auch Hamburger Unternehmen. Ist zwar nicht immer das Günstigste, aber für uns passt es wunderbar.
@flyingmama
verwechselst du vielleicht schlechte rechtschreibung mit regionalen dialekten?
@timo haberkern
es gibt keinen selbsterklaerenden code. das ist so wie area 51, bielefeld oder der heilige gral.
@mike
fuer regional eingesetzte software finde ich das den besten weg.
Bei uns sind die Kommentare auch in Englisch, weil wir ein internationales Team haben. Verschiedene Meetings sind daher auch auf Englisch.
In einem anderen Projekt hingegen haben wir auch deutsch kommentiert.
Aber ich teile da Timos Meinung. Wenn Klasse-, Funktions- und Variablen-Namen ordentlich gewählt sind, kann man die Kommentare auf ein Mindestmaß reduzieren. Wenn nichts dagegen spricht (Optimierungen o.ä.), sollte lesbarer Code die erste Prämisse sein.
Was sind Kommentare?
Mal im Ernst: sobald jemand von meinen Leuten anfängt, Kommentare zu schreiben, frage ich ihn/sie, wozu das gut sein soll.
Warum nicht gleich vernünftige Bezeichnungen einführen, einen Test schreiben oder ToDos sofort erledigen? Im Prinzip sind alle Kommentare inzwischen verboten worden.
[@miasin Es gibt zumindest „Intention-revealing code“. Und wenn das nicht hilft, werden dir die Tests die Antwort auf den Sinn geben…hoffentlich]
Diese Diskussion wird vor allem in DDD häufig geführt, wo die (Geschäfts-)Sprache der Code ist und umgekehrt (Ubiquitous Language). Prinzipiell spräche nichts dagegen, es in der Sprache des Unternehmens bzw. der Businesslogik zu machen. Die Restriktionen werden aber von der Programmiersprache vorgegeben. Man könnte natürlich eine eigene DSL einführen, nur macht das natürlich ungemein Arbeit.
Da man Übersetzungen jeglicher Art möglichst vermeiden sollte, weil dabei immer Informationen verloren gehen können, reduziert man es möglichst auf eine einzige. Die andere Übersetzung, die leider viel zu oft anzutreffen ist, ist das Entwickler Methoden und Klassen lustig nach ihrem Gusto benennen und in Gesprächen mit den Fachverantwortlichen es dann (bestenfalls) zu Irritation und (schlimmstenfalls zu) Missverständnissen kommt.
@Don Zampano
ken beck beschreibt das genial. keine frage. aber oft wird der code laenger, bloated. performance schreibt sich anders. aber du hast recht es ist eine moeglichkeit.
um die von dir beschriebenen irritationen zu vermeiden empfielt es sich jeden entwickler java lernen zu lassen. die werden sich freuen. aber dennoch wird einiges sinnvolles haengenbleiben.
@miasin
Der Code wird nicht bloated, im Gegenteil. Es entstehen zwar weitaus mehr Klassen und auch Zeilen, aber dafür ist jede einzelne so knapp wie möglich. Genau das ist ja das Tolle an TDD. Wenn ich „alten“ Code anschaue, habe ich Klassen und Methoden mit generischen Namen, die überhaupt nichts über die Aufgabe aussagen und fast jedes Prinzip von OOP missachten, SRP fast zu 100%.
Das ist das Problem von schlechter Benennung: Klassen wie „*_Manager“, „*-Core“ oder auch „User“ sind Gemischtwarenläden und Schlammklumpen, die auf jeden fall eine Menge an Kommentaren benötigen, um überhaupt verstanden zu werden.
Lieber mehr Code und dafür mit klarer Aussage und Aufgabe.
Und Performance ist dabei völlig uninteressant. Besser aufgeteilter und benannter Code erzeugt, wenn überhaupt, nicht wahrnehmbare Einbußen der Performance.
Im Gegenteil zeigte sich aus meiner Erfahrung heraus, dass dadurch die wahren Performancekiller gefunden werden konnten.
Denn das ist ja auch ein netter Nebeneffekt, wenn man Sprache als „Waffe“ in der Entwicklung einsetzt: es wird vieles viel klarer, Zusammenhänge erkennbar, Code modularer und damit verbesser- und verschnellerbar.
Sprache ist Verstand, warum nicht vernünftig einsetzen?
Ist eine Vereinbarungssache: Das Team – das _ganze_ Team – muss damit klarkommen. Wenn es auf Deutsch besser klar kommt, warum denn bitteschön nicht? Man könnte hier auch wieder das YAGNI-Prinzip und das KISS-Prinzip anwenden: Benutze deine Muttersprache, solange keiner fragt. Man redet ja sonst auch nicht auf Englisch, auch, wenn ich mir bei einigen Jugendfreunden nicht so ganz sicher bin 😉
Sicher muss der Kommentar vor allem eines erfüllen: Der, der den Kommentar liest, muss nachher mehr darüber wissen, was das Beschriebene macht als vorher… sonst macht ja der Kommentar keinen Sinn. Aber allein damit kommen ja schon viele nicht klar und schreiben viel zuviel Blödsinn rein. Kurz, aber klar formuliert in einer vereinbarten Sprache.
Generell kann ich jedem Entwickler empfehlen, sich mal das Kapitel Kommentare in der Pflichtlektüre „Clean Code“ von Uncle Bob (http://www.amazon.de/gp/product/3826655486) durchzulesen.
Wer danach keine andere Meinung hat, tja…
@Sascha
Wie gesagt, prinzipiell ist die Muttersprache bzw. die Domain-Sprache richtig. Und mit Tricks kann man sogar alle englischen Befehle von PHP eindeutschen und für externe Bibliotheken Wrapper, oh pardon … „Einhüller“ natürlich, schreiben.
Das wäre ideal, in der Tat.
Viel Spaß beim frei machen von Ressourcen dafür…
@don zampano
fuer so schlechte benennungen sollte bei entwicklern mittelalterliche strafen wie das abschlagen von koerperteilen oder das auf das rad flechten wieder eingefuehrt werden.
sprache ist verstand und setzt solchen voraus. das ist der einfache grund warum ir-code nicht klappt.
@don zampano
ich hatte einen kollegen der seine klassen ober, unter, haupt, neben genannt hat.
darauf angesprochen wurde er aergerlich. er haette sie voher immer oberklasse, unterklasse, hauptklasse oder nebenklasse genannt und sei angesprochen worden die namen seien unsinnig, deshalb hatte er jeweils klasse im namen weggelassen.
Ich habe bei uns auch eingeführt, dass wir in Deutsch kommentieren. Weil ich eben auch der Meinung war:
1. Lieber ein deutsches Kommentar was jeder versteht, als ein englisches was holperig und am Ende deshalb keinen Mehrwert bringt.
2. Die Hemmschwelle zu kommentieren ist niedriger
3. Und es spart auch geistige Ressourcen. Auch wenn man englisch kann, kostet der Switch Deutsch/ Englisch immer wieder Konzentration.
@sven
punkt 1 spricht sehr fuer deutsche kommentare:
es ist unglaublich was manchmal als angebliches englisch irgendwo auftaucht. da sollte man lieber bei seiner eigenen sprache bleiben und sich die eine oder andere peinlichkeit ersparen.
Als ich bin ja diesbezüglich auch eher ein Feind von Abweichungen von internationalen Standards und hätte immer auf englische Kommentare bestanden (aus Gründen die hier von anderen schon aufgeführt wurden).
Nun kam ich aber vor kurzem in ein Umfeld, indem deutsche Kommentare die Regel sind und englische Kommentare nur von bestimmten Zulieferen verwendet werden.
Natürlich habe ich mich sofort akribisch auf die Suche nach Problemen mit diesem „unprofessionellen“ Vorgehen begeben und hätte am liebsten Zeter und Mordio gerufen.
Allein ich musste feststellen, dass die deutschen Kommentaren viel besser sind als die englischen Pendants. Das auch Entwickler von anderen Firmen entbannt von irgendwelchen Vorschriften, plötzlich glasklare, gut verständliche, aber eben deutsche Kommentare verfassen können.
Das Englische ist offensichtlich eine Hürde auf dem Weg zu guten Kommentaren und wenn das das Ziel ist und nichts dagegen spricht, würde ich in Zukunft dort eine größere Freiheit erlauben.
Bei uns ist folgendes in den Coding Guidelines festgehalten:
– Kommentare immer auf deutsch (schon damit man die Geschäftslogik dahinter versteht)
– Klassen-, Methoden-, Funktions- und Dateinamen auf englisch
– sollte jemals jemand den Quelltext in einer anderen Sprache als deutsch kommentiert benötigen, so wird diese Sprache als Sekundärkommentar ergänzt
Alle Meinungen scheinen sinnvoll zu sein und im jeweiligen Kontext auch richtig.
Aber die Kernfrage bleibt immer noch:
Warum muss man Code überhaupt kommentieren?
Und vor allem: warum muss man Code kommentieren, damit man die Geschäftslogik dahinter versteht? Muss ich dann in einer bestimmetn Methode nachlesen, um komplexe Geschäftslogik und die Zusammenhänge zu verstehen? Brrr, da wird ja einem Angest und Bange.
Bisher konnte mir niemand glaubhauft widerlegen, warum sich Onkel Bob mit seiner Meinung, dass praktisch jeder Kommentar wenn nicht gefährlich so doch veraltet oder überflüssig ist, geirrt haben sollte.
Ich bin mir nicht sicher wieso sich die Diskussion hier so um Kommentare dreht. Für mich geht es bei deutsch/englisch hauptsächlich um die Methodennamen und nur zweitrangig um Kommentare
Also ich finde es immer schrecklich, wenn man Codebeispiele oder ganze Libaries im Internet findet mit französischen, russischen und was weiß ich was für Sprachen. Speziell wenn der Code recht unleserlich ist (formatierung oder einfach so dämlich programmiert) wird die Code-Analyse damit zur Qual.
Man schriebt nicht nur für sich oder sein Team sondern irgendwann für viele andere Leute auch und wenn euer Code nicht super-verständlich ist und ganz simpel macht ihr keinem einen Gefallen wenn ihr in Deutsch schreibst statt im international gut verständliche Englisch.
Ich bin dafür, die Dokumentation als solches in Deutsch zu schreiben wenn notwendig (z.B. weil der Firmenboss oder der Kunde kein Englisch können). Aber die KOMMENTARE sollten (wie der Code auch (also Methoden und Varablen) auf Englisch sein.
Just my 2 cent
@DonZampano: Es ist all das zu kommentieren, was sich nicht selbst erklärt bzw. es wird nur das warum, nicht aber das was kommentiert.
Beispiel für sich aus der Geschäftslogik ergebener Kommentarbedarf ist in der Touristik der Begriff Dauer, der zwar eigentlich mittels einer Ganzzahl abgebildet werden kann, je nach Kontext aber unterschiedliche Werte (für die selbe Reise) haben kann:
– Reisedauer in Tagen inkl. An- und Abreise
– Reisedauer in Tagen, aber ohne An- und Abreise
– Aufenthaltsdauer in Nächten
@Kai
public function testSomethingComplexThatHappensWhenXDoesY ()
public function testOtherComplexStuffOnDelivery ()
public function testThatOrderWontBeDeliveredIfClientPaymentIsOverdue ()
…
public function travelDurationWithArrivalAndDeparture ()
public function travelDurationForStayOnly ()
public function durationOfStayInNights ()
@Don Zampano:
Na klar kann man im Methodennamen alles mögliche verpacken und für PHPUnit würde ich zum Zwecke der TestDox-Erzeugung sogar mit dem Gedanken spielen.
Aber wie bitte willst du bei solch langen Namen dauerhaft innerhalb der maximalen Spaltenanzahl bleiben (es soll ja durchaus Methoden mit Parametern geben ;)) und wer übernimmt das umbenennen der Aufrufe, wenn sich der Methodenname aufgrund geändertem Inhalts zu ändern hat?
Meiner Meinung nach darf der Methodenname in etwa aussagen, was die Methode macht, aber die Details (z.B. @review, @todo, @throws, @global) gehören in den Kommentarblock. Ob der Rückgabetyp als erster Buchstabe in den Methodennamen gehört (z.B. iGetAmount) ist Geschmackssache, ich halte nichts davon und bevorzuge statt dessen @return.
@Kai Schröder:
Die Systems Hungarian Notation (m.E. großer Humbug) kannte ich eigentlich nur für Variablennamen, nicht für Methodennamen. Apps Hungarian Notation hingegen dürfte regelrecht üblich sein, erfordert aber keinen Mehraufwand. getAmount() sagt ja schon, was zurückgegeben wird.
Zu der ganzen Kommentargeschichte eine Anekdote (ich erhebe daher keinen allgemeinen Gültigkeitsanspruch):
Ich selbst verstehe oft Code ganz ohne Kommentare leichter als solchen mit mustergültigen Doc Comments. Der Grund ist ganz einfach – ich sehe mehr Methoden auf einmal, weil ich nicht mehr soviel scrollen muss.
Ein krasses Beispiel für das bei Anwenden scheinbarer „Best (Commenting) Practices“ aus dem DI-Container von Fabien Potencier (https://github.com/fabpot/dependency-injection, den ich übrigens selbst gern verwende) – dieses hatte ich mir seinerzeit mal genauer angeschaut (Code lesen kommt immer gut):
Originalcode (11 Zeilen):
/**
* Gets the service associated with the given identifier.
*
* @param string The service identifier
*
* @return mixed The service instance associated with the given identifier
*/
public function __get($id)
{
return $this->getService($id);
}
Von mir modifiziert, um besser den Code lesen zu können:
public function __get($id){
return $this->getService($id);}
Danach konnte ich wesentlich besser nachvollziehen, was passiert. Vor allem nervte mich das Scrollen nicht mehr so sehr. 😉
@Kai
Das mit der Spaltenanzahl ist ein Witz, oder?
Oder hast du etwa deine maximale Spaltenanzahl auf 30 gesetzt?…
Was ist denn besser: aus dem Namen der Methode den Sinn und Zweck (und keinerlei Interna!) heraus zu lesen und dabei die gleiche Sprache wie die Geschäftssprache zu verwenden oder es erst über Kommentare und Raten herauszufinden?
Das Umbenennen ist auch kein Problem: ändern sich die Anforderungen, ändern sich die Methoden. Oder willst du Methoden niemals umbenennen, weil es zu aufwändig ist, sie dafür aber nicht mehr das tun, wonach sie ursprünglich benannt wurden? The only constant thing is change.
Was Parameter angeht, kann ich auch wieder nur auf Clean Code et. al. hinweisen: die beste Methode hat keinen Parameter, gefolgt von 1, 2 und maximal 3. Alles danach ist Unsinn und sollte eher mit POPOs gelöst werden.
Abgesehen davon, dass die Anzahl der zu testenden Fälle mit der Anzahl der Parameter exponential steigt.
Vorteile?
Kleinere Klassen, kleinere Methoden, kleinere Fälle zu testen, weniger Komplexität. Lieber 10 Klassen/Methoden mehr als alles in einer God-Class. Usw, usw…
Und egal ob Kommentare oder Interfaces von Klassen, methoden etc. – Lesbarkeit ist die halbe Miete. Und wenn der Fluss dadurch gestört wird, dass überall mittendrin Kommentare oder Docblocks sind oder man darüber nachdenken muss, was da passiert, ist das schlecht.
Jeder mentale Break birgt Gefahren.
Ich habe festgestellt, dass viele Kollegen Migrationshintergrund haben.
Wir konnten froh sein, wenn die Kollegen halbwegs gut Englisch konnten. Komplexe deutsche Sätze eines Muttersprachlers „lesen“ war schon recht holprig, von „schreiben“ wollen wir gar nicht sprechen. Englisch hatte da den Vorteil, dass es alle konnten und man sich an ein einheitliches, vereinfachtes Vokabular gehalten hat. Wir hatten keine „Muttersprachler“, die komplizierte Vokabeln verwenden konnten.
Bei Open-Source hingegen ist es sowieso unstrittig. Ich habe mal versucht mich an einem Projekt zu beteiligen und festgestellt, dass es in Tschechisch kommentiert war. Das hilft mir natürlich nicht weiter.
Von „Clean-Code“ im Sinne von „selbsterklärend“ halte ich nichts. Aus Code – egal wie „selbsterklärend“ er ist – kann ich keine (gute) Doku generieren. Letztere möchte ich aber ausdrücklich haben.
Ich habe im Data-Warehousing / Business-Reporting gearbeitet und musste von den Codern nachträglich ein Data-Dictionary anfordern. Denn ohne kann man im Reporting keine Tasks erstellen. Die haben geflucht ohne Ende, mit ihrem „selbsterklärenden“ Code, als sie Monate später versuchten herauszufinden, was der eigentlich tut.
Klassisches Beispiel: „setWeight($weight)“ … selbsterklärend? Nein: 1) in welcher Einheit? 2) welcher Wertebereich? 3) was passiert bei negativen Werten? 4) Float, Integer oder String? 5) ist int(0) erlaubt? 6) Ist der Wert absolut oder in Prozent? Brutto- oder Nettogewicht? … die Liste lässt sich fortsetzen. Daher meine Meinung: „selbsterklärend“ ist eine Illusion.
Da stellte sich bspw. heraus, dass es ein Briefgewicht ist und die Einheit abhängig vom gewählten Vertragspartner. Der steht in einem anderen Objekt. Es ist aber Nettogewicht – also ohne Verpackung. Deren Gewicht steht in einem dritten Objekt, aber in der Hauseinheit.
Nun sollte der preisgünstigste Versanddienstleister automatisch anhand Gewicht und Abmessungen gewählt werden. Dank „selbsterklärendem“ Code, hat jemand das Netto- und nicht das Bruttogewicht verwendet. Die Folge: Ware wurde zu teuer oder gar nicht ausgeliefert. Unsere Firma musste dem Kunden den Verlust ersetzen.
Wenn man erlebt hat, dass BWLer 2 Wochen darüber meeten, wie „Nachfrage“ exakt zu definieren sei und ob beispielsweise ein Expresszuschlag Teil der Nachfrage ist oder nicht – dann versteht man, dass nichts selbsterklärend ist.
Bei den Einheiten geht es schon los: wenn ein Europäer „selbsterklärend“ an Kilogramm denkt, ist für einen Amerikaner ganz klar, dass es Pfund ist. Längenangaben – Kilometer versus Meilen. Geldwerte – welche Währung? Zeitangaben – welche Zeitzone und welches Format, mit oder ohne Sommerzeit und wenn ja: amerikanische oder europäische Sommerzeit? Kalenderwochen – nach europäischen oder amerikanischem Standard? Indexe als Integer – fangen wir bei 0 an oder bei 1?
Ist die Eigenschaft statisch, virtuell (berechnet), transient, persistent und wie sieht die Berechnungsvorschrift aus? In welcher Kundenanforderung ist das definiert – denn das muss ich nachweisen können, wenn die Abrechnung am Ende nicht stimmt.
Wir hatten einen Kunden, der wissen wollte, warum sich sein Lagerwert rückwirkend ändert. Der Coder dachte es wäre „selbsterklärend“, dass er stets vom aktuellen gleitenden Einkaufspreis und nicht dem historischen Wert der Ware zum Zeitpunkt des Reports ausgeht. Das ging bis zur Geschäftsleitung und ergab Regressforderungen.
Das ist eben gerade nicht alles selbsterklärend. Mal ganz zu schweigen davon, dass der Quellcode weder in der Autovervollständigung der IDE noch in der HTML-Doku angezeigt wird … und weder das eine noch das andere funktioniert überhaupt ohne Kommentare. Mal ganz abgesehen von dem Leuten im Support, die dem Kunden erklären müssen, warum er sein „Umsatz“ im Reporting 2% geringer ist als sein Taschenrechner behauptet.
Ich meine: gute Kommentare schreiben will gelernt sein.
@Tom
Alles ja ganz nette Beispiele, allerdings zeigt es nur, dass es schon Erfahrung braucht, so etwas zu tun. Und das in vielen deiner Beispiele die Leute es einfach nicht gut genug gemacht haben.
„Gut genug“ heißt eben auch, dass es dem entspricht, worüber auch geredet und gewirtschaftet wird.
Es geht auch nicht um selbsterklärend, „intention-revealing“ heißt das nicht, sondern viel eher „welchen Zweck verfolgt diese Methode“.
Das dies nicht immer selbsterklärend ist, liegt auf der Hand. Genauso wie viele deiner Beispiele auch nicht für einem BWLer sofort selbsterklärend sind. Komplexe Zusammenhänge erscgließen sich eben nicht immer sofort, weder im Code noch real.
Meinst du ernsthaft, ein Kommentar über oder in so einer Methode würde es verbessern? Wer soll den korrekt schreiben, dass ihn jeder folgende Entwickler versteht? Wer pflegt ihn bei Änderungen? Wie viel % der Kommentare in einer umfangreichen Codebasis sind nach Monaten oder Jahren korrekt, hilfreich oder überhaupt noch aktuell?
Oder sprichst du von DocBlocks?
Da macht es schon eher Sinn, auch aus Dokumentationssicht.
Aber selbst dort würde man ja als Text zu einer Methode nicht das gleiche in Prosa schreiben (wollen):
// Ändert die Adresse
changeAddress(…)
Ach was, tatsächlich?
Zu deinem Beispiel setWeight($weight).
Ich stimme dir zu, dass deine beschriebenen Fälle nicht so funktionieren. Aber vielleicht so:
setNetWeight(Weight $weight), setGrossWeight(Weight $weight), setRelativeWeight(Percentage $p)
Weight ist ein Value Object, dass mit Menge und Einheit gebildet wird und auch die Umrechnung selbst vornimmt.
(Das ist übrigens die unglaublich oft unterschätzte Stärke von Value Objects)
Wenn man nicht weit genug denkt, erreicht man nicht viel sondern eher weniger, das stimmt. Aber genau das trennt die Spreu vom Weizen bei den Entwicklern.
@Tom: Du möchtest selbsterklärenden Code anhand eines Beispiels für nicht selbsterklärenden Code für ungültig erklären.
Du schreibst, es handele sich um ein Briefgewicht. Nun weiß ich nicht, ob das schon aus der Klasse, zu der setWeight() gehört, ersichtlich ist, aber falls nicht, wäre setMailWeight() korrekt. Es gibt einen Unterschied zwischen Brutto- und Nettogewicht, Netto ist gemeint? setMailNetWeight() (passend zum Artikel-Thema: „Netto“ ist gemeint, ich hoffe, „net“ ist in diesem Fall korrekt). Es ist nicht klar, was $weight eigentlich ist? Nun, PHP hat Type Hints: setMailNetWeight(Weight $weight). Weight wäre in diesem Fall eine projektweit einheitlich verwendbare Klasse. Je nach Architektur und wie „enterprisey“ es werden soll, kämen natürlich auch setMailWeight(MailWeightSpec $weight) o.ä. in Frage.
Bei dem Beispiel mit den Amerikanern und den Europäern und den Einheiten ähnliches: Wenn man wirklich mit beiden zu tun hat, sollten Länge bzw. Masse einfach gekapselt werden und entsprechende Umrechungsfunktionalität von allen Methoden ferngehalten werden, die damit zu tun haben.
Insbesondere der Fall mit dem sich ändernden Wert des Lagerhauses hat nun wiederum überhaupt nichts mit dem Code selbst zu tun. Wenn da im Kommentar gestanden hätte, dass zur Berechnung der aktuelle Einkaufspreis genommen wird, wäre der Fehler doch genauso aufgetreten. Zumal das Programm so ja auch durch die sicherlich vorhandenen Tests gelaufen ist, d.h. entweder steht das in der Spezifikation schon falsch drin oder bei der Umsetzung der Vorgaben in Tests ist was schiefgelaufen.
Übrigens ist die Agile-Bewegung angetreten, um genau so etwas zu vermeiden.
@Timo
Oops, da waren wir zeitgleich und fast analog in der Aussage
😉
Und du warst schneller als ich, verflixt! Andererseits: Zwar fängt der frühe Vogel den Wurm, aber die zweite Maus kriegt den Käse!
Zu deinem Beispiel mit changeAddress(…) – genau sowas kenne ich auch! Da hat man schön herumprogrammiert und nun sollen die Doc Comments her, weil Vorgabe/“das macht man so“/Was-auch-immer und dann kommt sowas raus:
/**
* Sells mother for price.
*
* @param $buyer A moral-free customer.
* @param $price The price to pay.
*
* @return The vendor, now at least an half-orphan.
*/
sellMother(Customer $buyer, MoneyAmount $price){ /* … */ }
Ganz ehrlich – braucht irgendjemand einen Kommentar, um zu erkennen, was dort passiert?
lol
Ich brauche einen Kommentar…sonst glaube ich nicht, was ich da sehe
😉
Nichts, wir schreiben die Kommentare auf deutsch 🙂
Bei Klassen- und Funktionsnamen sieht’s anders aus… buntes Denglisch
Ich werd mich in Zukunft auch eher an den Muttersprachenkommentaren halten. Das ist für mich einfacher – letztlich zählt irgendwo auch die Einfachheit. SOLLTE es dann irgendwann doch mal „international“ gehen, kann mans immer noch ins Englische übersetzen. Macht zwar etwas mehr Arbeit, treibt aber sicherlich auch niemandem die Tränen in die Augen. Zumal man das dann von jemanden machen lassen kann, der des Englischen womöglich mächtiger ist als man selbst.
„Ich kommentier nur auf Deutsch, da die Kommentare eh nur für mich und ab und zu einige (deutsche) Kollegen gedacht sind. Warum sollte ich da alles extra übersetzen?“
Wiederverwendung und Wartbarkeit. Die Aussage kann man für ein bestimmtes Projekt und einen bestimmten Zeitpunkt treffen, nicht jedoch für zukünftige Projekte und auch nicht für die Entwicklung eines Projektes oder einer Firma. Warum sollen für Closed Source Projekte andere (geringere) Standards als für Open Source Projekte gelten?
Bei Bezeichnern eine andere Sprache als Englisch zu verwenden, wird sich früher oder später rächen. Man hat Bezeichner in zwei Sprachen, da sowohl PHP selbst, wie auch externe Bibliotheken Englisch nutzen werden.
Während man bei Kommentare auch noch über eine nachträglich übersetzen kann, wenn der Bedarf auftritt (Wobei der Aufwand dann deutlich höher sein wird), ist dies bei Bezeichnern nicht möglich. Man würde die APIs brechen.
@Tom: Aber vielleicht gilt auch hier „You ain’t gonna need it“ … also zumindest für die Kommentare, Funktionsnamen und Co. habe ich ja explizit ausgeklammert.
@Timo Reitz Dein Hinweis ist zweischneidig:
setMailAbsoluteNetWeigthInUnitTakenFromSellerClass…($weigthAsFloat)
Mir persönlich ist ein sinnvoll formulierter Satz lieber (und leichter lesbar).
„sellMother()“-Beispiel: was ist „Mother“? Eine Member-Variable? Was ist „price“? Welche Einheit hat Price und welchen Datentyp? Kann „price“ negativ sein? Wird eine Exception geworfen? Was ändert sich am Customer-Objekt? Wird dessen „Mother“ überschrieben oder hat er dann zwei?
@Don Zampano Die Pflege von DocBlocks kann man IMHO einem Entwickler zumuten. (Wiki wäre schwieriger.)
ValueObjects sind besser als Nichts, aber auch aufwendiger und lösen nur einen Teil des Problems. Was ist mit Rückgabewerten und Exceptions?
Vorsicht mit „Clean-Code“: offensichtlich sprach der Autor doch von Java&Co. – nicht PHP. Viele Infos im Java-Funktionskopf MUSS man in PHP dokumentieren, weil es kein Sprachkonstrukt dafür gibt. Direktvergleich:
PHP:
public function setWeight($netWeight) {…}
Java:
public Tld.Ecommerce.Delivery.Service.Provider setWeigth(Float netWeight)
throws NegativeWeightException, UndefinedUnitException,
NoProviderFoundException, MaxWeightExceededException
@assert weight(min=0.1,max=60.0) { … }
Zu der Ausrede: „Ich weiß nicht, was im Doc-Block einer (API-)Doku stehen soll“. Ein Fachinformatiker kann sich das leisten, aber an der Uni war das AFAIK alles Prüfungsstoff.
2. Semester Grundstudium: Vorbedingungen, Nachbedingungen, Invarianten.
1. Semester Hauptstudium: Aufbau eines Data-Dictionary.
Semesterangaben können im Einzelfall geringfügig abweichen. Ein Absolvent einer deutschen Uni möchte das eigentlich beherrschen (oder wissen, wo er es nachlesen kann). Das ist der höchste Abschluss in Informatik weltweit. Wenn ihr es nicht wisst, ist der Welt nicht zu helfen.
@Tom:
setMailAbsoluteNetWeigthInUnitTakenFromSellerClass…($weigthAsFloat)
Darum habe ich ja geschrieben, dass es letztlich davon abhängt, was genau gemacht wird. Im Zweifelsfall handelt es sich eben nicht um eine einzelne Methode, sondern müsste aufgesplittet werden.
„“sellMother()”-Beispiel: was ist “Mother”?“
Das hinge vom Kontext ab, vermutlich aber die Mutter des Besitzers der Methode.
„Eine Member-Variable?“
Käme drauf. Falls sellMother() public ist, sicher nicht.
„Was ist “price”?“
Ein Preis?
„Welche Einheit hat Price und welchen Datentyp?“
Der Datentyp steht dort, dieser sollte dann auch die Einheit beinhalten.
„Kann “price” negativ sein? Wird eine Exception geworfen? Was ändert sich am Customer-Objekt? Wird dessen “Mother” überschrieben oder hat er dann zwei?“
Wer weiß das schon in einem Beispiel, dass nur einem schnellen Gedanken entsprungen ist? Im schlimmsten Fall wäre meine Methode eben auch nur ein Beispiel für eben nicht selbstverständlichen Code. Wie Don Zampano schrieb, leicht ist es nicht.
Allerdings: Wenn man das Ganze vernünftig gestaltet, sind Methoden sowieso nie sehr lang, eher eine Handvoll Zeilen. Wenn es gar nicht anders geht, schaut man eben dort rein, wo dann – hoffentlich – der selbstverständliche Code ist.
„throws NegativeWeightException, UndefinedUnitException,
NoProviderFoundException, MaxWeightExceededException“
Igitt, checked exceptions. 😛
Ich kommentiere schon immer in Deutsch. Schon weil mein Englisch eher mau ist, mein Deutsch aber (fast) hervorragend 🙂 Und potentielle Entwickler nach mir wohl auch Deutsch lesen können werden.
Bei Klassennamen bleibe ich ganz klar im Englischen. Erstens ist der Lesefluß im Code besser, zweitens werden viele Fachbegriffe (Controller, etc.) üblicherweise nicht übersetzt, drittens sind die Bezeichner schlicht kürzer und viertens bringe ich es nicht übers Herz, Umlaute in Bezeichnern zu verwenden (was wohl zumindest tw. geht) – ohne Umlaute aber braucht man auch kein Deutsch verwenden. Fällt mir gleich 5. ein: Selbst wenn das Charsetting der Datei flöten geht, bleibt der Code lauffähig.
@Tom
>ValueObjects sind besser als Nichts, aber auch aufwendiger und lösen nur >einen Teil des Problems. Was ist mit Rückgabewerten und Exceptions?
Du denkst bei deinem angegeben Beispiel viel zu sehr in alten Strukturen, (aka „Datenzentrierter OOP“). Genauso wie beim Beispiel mit der überlang benannten Methode – offensichtlich ist dabei nicht zu Ende gedacht worden.
So eine Methode ist mit hoher Wahrscheinlichkeit falsch platziert, man weiß nicht was die Bestandteile bedeuten etc. etc. (allein schon „…takenFromSellerClass“ … wtf?)
VOs sind mit die beste „Erfindung“ seit Jahren.
Denn sie beantworten und erledigen genau diese Fragen und Probleme.
Bevor ich setWeight aufrufe, erzeuge ich ein Weight VO. Falls dieses bereits ungültige Werte bekommt, ist der Fall erst mal erledigt, da es nie ungültig erstellt werden kann. D.h. setWeight kann sich zumindest darauf verlassen, ein gültiges Gewicht zu bekommen.
Was der Rest (Rückgabetyp und Exceptions) in dem hier besprochenem Kontext für eine Rolle spielt ist völlig unklar. Das hat wohl nichts mit Benennungen und Kommentaren zu tun.
Ich möchte hier aber auf einen viel wichtigeren Aspekt der letzten Beispiele hinweisen:
eine Methode setWeight…() würde ich wohl niemals schreiben!
Denn warum sollte ich das Gewicht von etwas setzen?
Ich denke, diese Eigenschaft hat das „Ding“ bereits von sich aus.
So fängt oft das Nachdenken über guten Code schon an und erspart etliche Kommentare, die soclhe Sachverhalte eben nicht im Code umsetzen…
Ich verweigere das weitere lesen der Kommentare nach dem ich beim überfliegen die Studiert ist besser als gelernt bemerkungen gelesen habe.
Über sowas kann ich mich mal unterhalten wenn ich nach nem Kneipenbesuch auf die Bahn warte 🙂
@Don Zampano Ach, wenn es mal so einfach wäre, wie du denkst. Schon mal mit einem BWLer als Kunden gearbeitet? Der sagt dir „das muss aber so“ und damit ist die Diskussion beendet.
Ich sage gar nichts gegen VOs, aber sie ersetzen die Doku nicht. Es gibt einfach Dinge, die sind nicht trivial.
Wie ist denn unsere tägliche Praxis? Beispiel:
Definition „Wareneinsatz“ = ist für jede Rechnungsposition die Zahl der georderten, gelieferten und nicht retournierten Posten multipliziert mit dem historisierten gleitenden Einstandspreis zum Zeitpunkt der Rechnungsstellung, zuzüglich dem gleitenden Einstandspreis der Geschenke, abzüglich der virtuellen Posten, zuzüglich der anteiligen Druckkosten der beigelegten Kataloge, umgerechnet in die Hauswährung des Marketingcenters. Und wenn die Ware in mehreren Teillieferungen gesendet wurde, musst du die Positionen natürlich vorher splitten und anteilig berechnen.
Du hast eine halbe Stunde Zeit, denn wir haben noch 64 weitere Kennzahlen.
Wenn du fertig bist, beantrage mal ein Meeting mit den Jungs vom Reporting. Die wollen Anforderungen von dir, wie deine Zahlen in N-dimensionale Hypercubes einzuordnen und aufzusummieren sind. Dazu müssen sie für jede Kennzahl wissen, welche gemeinsamen Aggregationsdimensionen du verwendest, ob du neue einführst und welche Kardinalitäten du benutzt. Und sie brauchen eine schriftliche Schnittstellenbeschreibung damit sie das im ETL-Tool modellieren können. Außerdem brauchen sie eine Prognose des Datenaufkommens, damit sie entscheiden können, ob sie eine Aggregationstabelle brauchen.
BTW: und die Tester kommen nachher vorbei, denen musst du dringend eine Berechnungsformel erklären. Wir sollten die Produktgruppen nach „Gartensaison“ und nach „Saatsaison“ kumulieren, abhängig vom Standardort des Marketingcenters. Der Kunde meint, die Zahlen sehen „komisch“ aus.
Und um 14:00 haben wir ein Kundenmeeting. Da geht es dann darum, ob Expresszuschläge auf die Versandkosten zur Nachfrage gerechnet werden oder nicht.
Habe ich live erlebt. Jedes Subsystem mit ca. 150-250 Klassen. 5 Entwicklungsabteilungen, 40 Entwickler. Und dann kommt tatsächlich so ein Trottel mit der Schnittstelle zur Steuerung einer Saatgutsortieranlage und erklärt dir: „der Quellcode ist die Doku – ist alles selbsterklärend“.
@Tom
Du hast recht, in einer anderen Domain kenne ich so etwas fast haargenau.
Aber genau das, was du da beschreibst, spricht gegen eine (vernünftige) Dokumentation!
Wer schreibt die denn? Meine Entwickler haben dafür keine Zeit, eben weil sich die Anforderungen ständig ändern.
Und ich stimme dir auch zu, die BWLer oder Projektleiter haben auch nicht den vollen Durchblick, sie bekommen die Anforderungen von anderen (GL, Kunden). Sollen die eine Doku schreiben? No way.
Ergo gibt es eigentlich niemanden dafür. Und wenn es eine oder mehrere Personen gäbe, es müssten Vollzeitkräfte sein, die ständig mit und von allen Beteiligten Informationen sammeln werden.
Wer bezahlt solche Leute?
Und selbst Kommentare unterliegen allen Gefahren (und noch mehr), die auch eine „halbherzige“ Doku erleiden kann: man schreibt sie, aktualisiert sie einmal, zweimal…aber der entsprechende Code ändert sich noch öfter und es ensteht das typische Kommentarunkraut.
Ich zumindest habe in meinen 20 Jahren nicht ein einziges größeres Projekt gesehen, dessen Doku (klassisch oder inline) auch nur annähernd aktuell oder nützlich gewesen wäre, wohl aber einige, wo dies fast schon gefährlich mit Falschinformationen durchsetzt war.
Ausnahmen sind natürlich APIs oder offene Projekte, da geht es nicht ohne. Obwohl es ja da auch jede Menge Beispiele gibt, deren Doku nie auf dem aktuellen Stand ist…
Deshalb ist es fast unabdingbar, Code so zu schreiben, dass die einzelnen Elemente so aussagekräftig wie möglich sind und vor allem testbar und extrem wartbar sind.
„Selbsterklärend“ hatte ich ja schon ebenfalls als Illusion bestätigt; „zweckdienlich“ oder „absichtserklärend“ treffen es vielleicht besser, bessere deutsche Worte für das sehr verständliche „intention-revealing“ fallen mir gerade nicht ein. Man kann nicht alles gut eindeutschen 😉
PS:
Natürlich sind VOs nicht mit einer Doku vergleichbar. Aber sie sind ein ideales Mittel, neben anderen nützlichen Patterns wie Specification oder Policy, komplexe Sachverhalte in Software zu modellieren. Das sie sehr leicht zu testen, handhaben und zu vermitteln sind und dadurch Änderungen sehr leicht machen, sind sie um so wertvoller.
@Don Zampano Ja, das kann man so sehen.
Vielleicht einigen wir uns darauf, dass es sinnvoll ist nach einem festen Muster vorzugehen, was die API-Doku angeht.
Was mir nämlich immer wieder auffällt: viele Junior Developer haben Schwierigkeiten gute Kommentare zu schreiben. Die Seniors kannst du allein arbeiten lassen, aber bei den Frischlingen lohnt stets ein prüfender Blick. Auch verstehen die Neuen manche Dinge nicht, die für die alten Hasen selbstverständlich sind.
Deshalb ist eine allgemeine Policy, was man von Kommentaren erwartet durchaus hilfreich.
Einer unserer Juniors kam bspw. damit an:
class Producer {
protected $file;
…
}
Die Membervariable $file wird verwendet, aber nirgends initialisiert. Auf die Frage wieso, meinte er: die abgeleitete Klasse muss das machen.
Als ich fragte, woher der Entwickler das wissen soll, antwortete er: das sieht man doch!
Ich habe folgendes Konstrukt vorgeschlagen:
abstract class Producer {
/**
* Returns an open file handle for reading and writing.
* @return resource
*/
abstract protected function _getFile();
…
}
Wollte er aber nicht verwenden. War ihm zu viel Text.
Ergebnis: Der nächste Entwickler, der damit arbeiten musste, hat sich seine eigene Lösung geschrieben.
Das es anders geht zeigte unser anderer Junior.
DocBlock mit Anwendungsbeispiel, eine Anleitung wie man die Funktion als CronJob einrichtet und Verweise auf die von ihm verwendeten Online-Tutorials. Außerdem an einer problematischen Codestelle Hinweise auf einen Workaround für ein Serverproblem, mit Link auf den Bug-Tracker, wo er das Problem gemeldet hat.
Das konnten wir während seines Urlaubs problemlos in Betrieb nehmen.