Was sind Annotations?
In der Software-Entwicklung werden Annotations verwendet, um die Dokumentation und Kommentierung des Quellcodes
zu verbessern. Für das ausführbare Programm sind Annotations völlig irrelevant.
Annotations unter PHP
In PHP findet man Annotations im Zusammenhang mit phpDoc-Kommentaren. PhpDoc-Kommentare werden verwendet, um Dateien, Klassen, Funktionen, Klassen-Eigenschaften und Methoden einheitlich zu beschreiben. Dort steht z.B. welche Parameter eine Funktion erwartet, welchen Rückgabewert es gibt oder welche Variablen-Typen verwendet werden.
Hier ein kleines Beispiel:
/** * Beschreibung der Datei. * * @author Name XYZ * @pacakge Lorem ipsum * @copyright Urherberrechtshinweis * @license GNU/GPL * @version 1.0 */ /** * Beschreibung der Klassse. * * @category Dolor sit * @subpackage Lorem ipsum dolor */ class MeineKlasse { /** * Beschreibung der Eigenschaft. * * @var integer */ protected $eigenschaft = 0; /** * Beschreibung der Methode. * * @param integer $eigenschaft * @return boolean */ public function setEigenschaft($eigenschaft) { $this->eigenschaft = $eigenschaft; return true; } } |
Die einheitliche Syntax der Kommentare wird unter anderem von den Entwicklungsumgebungen Zend Studio, Eclipse PDT oder NetBeans verwendet, um dem Entwickler weitere Informationen zu liefern. Außerdem nutzt der phpDocumentor die Kommentarblocks zur Generierung einer technischen Dokumentation.
Das klingt doch super. Warum sollten Annotations also böse sein?
Na ja, Annotations selbst sind vielleicht nicht böse, aber in einigen Fällen können sie böse werden. Z.B. dann, wenn man in Annotations Programmlogik versteckt. Also, wenn sich Annotations direkt auf das Verhalten des Programms auswirken.
So wird es leider im neuen TYPO3 5.0 Framework Flow3 gehandhabt. In Flow3 können Annotations u.a. eingesetzt werden, um Model-Eigenschaften zu validieren und das ist meiner Meinung nach keine gute Lösung. Denn Annotations sind ja erst einmal nur Kommentare und die werden bekanntlich vom Compiler (bzw. in PHP vom Interpreter) ignoriert. Leider ist PHP trotzdem in der Lage, durch die Reflection-API die Annotations auszuwerten. Hier wird also das Verhalten des Programms durch einen Kommentar direkt beeinflusst. Kommentare haben den Nachteil, das sie gerne überlesen oder entfernt werden und dann wird es umso schwieriger, eventuell auftretende Fehler zu finden.
Also liebe Entwickler von TYPO3 5.0 und alle anderen, die in Annotations gerne Programmlogik verpacken: Bitte überdenkt diese Programmierweise nochmals. Solange Annotations in PHP noch nicht als eigenes Sprachkonstrukt existieren (anders als in Java), sollten Kommentare immer entfernt werden können, ohne dabei das Verhalten des Programms zu beeinflussen.
DocBlockComments sind eine sehr gute und weit unterstütze Methode um seinen Code zu kommentieren. Es liegt also recht nahe, die dort definierten Sachen (Validatoren) auch im Programm zu verwenden.
Wenn man vorher die Dokumentation anschaut, wird doch recht schnell klar, dass in FLOW3 Annotations benutzt werden. Ich sehe da keine Gefahr, dass das mal eben gelöscht wird.
„Kommentare haben den Nachteil, das sie gerne mal überlesen oder entfernt werden“
Naja, das ist alles eine Gewöhnungssache. Wenn man weiß, dass wichtiger Inhalt drin steht, verkneift man sich auch, die eben mal zu löschen.
Ich finde die Annotationen sehr gut, weil sie Nebenaufgaben (Validierung, Casting, Error-Handling-Config) in einfacher und übersichtlicher Notation erlauben und den eigentlichen Programmcode sauber halten.
regards, foertel
wenn du schon bei annotationen meckerst, warte auf aspekt orientierte programmierung in flow3.
ps der erste satz ist falsch. annotationen werden sehr wohl in der software programmierung eingesetzt um ausführbaren code zu beeinflussen
@foertel:
„Wenn man weiß, dass wichtiger Inhalt drin steht“
Davon sollte man aber nicht immer ausgehen. Andere kennen deinen Programmcode vielleicht nicht so gut.
Annotations an sich sind ja ne coole Sache, aber er der Autor hat schon Recht wenn er sagt, dass es in PHP noch keinen Sinn hat in dieser Art und Weise damit zu arbeiten.
Ich bin aber zuversichtlich, dass wir dieses Feature in einer der nächsten PHP-Releases als eigenständiges Sprachkonstrukt nutzen dürfen 😉
Ich hatte gerade das ’schmerzlich‘ mit unserer ersten Extbase-Erweiterung erfahren müssen. Die ist uns um die Ohren geflogen, weil beim Provider eAccelerator installiert war und die Kommentare rausgefiltert wurden.
Den Lösungsansatz in Extbase und Flow3 Annotations zum Validieren zu verwenden finde ich nicht so glücklich.
Für grosse Webseiten wo man alles tut um die Performance zu steigen und den Quellcode so gering wie möglich zu halten, eigentlich ein ’no-go‘
Dem kann ich überhaupt nicht zustimmen, gerade bei großen Anwendungen will man den Quellcode kompakt halten und für so generische Dinge wie Validierung, Filterung, Mapping Informationen vielleicht sogar ACL so wenig Code wie möglich schreiben, damit die Anwendung schnell und einfach erweiterbar ist. Oft sind das dann auch Informationen, die für die eigentliche Problemlösung nicht relevant sind.
Das Doctrine ORM nutzt z.B. Annotations um Mapping Informationen in Entityklassen auszulesen, PHPUnit verwendet den Ansatz seit Jahren für Metainformationen!
Und was das Rausfiltern von Kommentaren angeht: DAS ist ein no-go! Kommentare sind Dokumentation und gehören somit zum Code. Wer mal „versehentlich“ Kommentare rauslöscht hat da wohl was extrem falsch verstanden.
Das einzige Problem an den Annotations ist, dass es teuer ist, sie auszulesen per Reflection. Das lässt sich aber mit Caching lösen.
@Merteman: >>Davon sollte man aber nicht immer ausgehen. Andere kennen deinen Programmcode vielleicht nicht so gut.<<
Wie foertel schon sagt: es ist alles eine Gewöhnungssache. DocBlock-Annotations erwecken m.E. auch nicht den Eindruck eines Kommentars (auch wenn es syntaktisch einer ist), sondern von "'was wichtigem". Wenn Du wirklich die Gefahr siehst, dass das gelöscht wird, solltest Du die Regel dahingehend erweitern, dass alles, was ein @ davor hat, nicht bedenkenlos gelöscht werden darf.
"Wichtige" Annotationen sind ja all jene mit einem @ davor.
Dem Artikel kann ich nicht zustimmen. Annotations sind ein wertvolles Konstrukt, welches sehr wohl auf die Programmlogik Einfluss haben kann und soll. Gerade in Java werden Annotations häufig verwendet, z.B. in JPA für ORM. Das macht übrigens in PHP Doctrine auch: http://www.doctrine-project.org/docs/orm/2.0/en/reference/annotations-reference.html – ich kann also z.B. ein Attribut einer Klasse deklarativ auf ein DB-Feld mappen, ohne dafür extra XML-Definitionen erstellen zu müssen (oder schlimmer – dies irgendwo im Code vergraben zu müssen).
Annotations in Kommentaren sind ein absolutes Unding, das geht überhaupt nicht, auch wenn bei Doctrine oder Flow3 bereits fleißig damit gearbeitet wird. Ich bin jetzt nicht der 150prozentige Hardliner, aber es gibt sinnvolle Alternativen, z.B. in das Verhalten als Konfiguration in statischen Daten des Modelobjekts festzulegen.
Annotations sind meiner Meinung nach eine sehr sinnvolle und elegante Lösung um (gerade wie in FLOW3) IoC, AOP oder ORM zu implementieren. Methoden mit Validatoren „Auszuzeichnen“ ist ebenfalls sehr übersichtlich und führt zu gut lesbaren Code.
Das die Annotations im Kommentar stehen müssen liegt eher an PHP, welches sie nicht unterstützt, hier sollten sie sich ein Beispiel an Java nehmen (wobei dort Annotations auch erst ab Version 5 vorhanden waren).
@Bachi: Das „Gerade in Java“-Argument ist schonmal Schwachsinn. PHP ist kein Java UND in Java sind Annotations ein fester Bestandteil der Sprache – anders als in PHP, wo man nur Mittels Reflection darauf zugreifen kann.
Ich stelle aber nochmal ein anders Argument in den Raum: Fehler in Annotations lassen sich nicht debuggen!
Die Grenze mit dem „Sparchbestandteil“ ist in Java aber weich. Es gibt zwar sparchimmanente Annotations, aber viele Annotations werden vorgegeben um die Implementierung der damit verbundenen Logik den Frameworks zu überlassen. Die Annotations werden dann im Idealfall Standard. Dann sind sie für alle lesbar und sparen jede Menge Code. Mit PHP sind wir in der Regel langsamer als in Java, weil wir alles selber schreiben müssen. Das bessert sich aber. In der Persistence eifert PHP glücklicherwiese Java nach. Momentan haben wir PDO, was gefüht wie JDBC ist. Bald haben wir bestimmt auch JPA. Ich freue mich jedenfalls auf die Annotations.
Ein alter aber spannender Thread 🙂
Ich kannte Doctrine2 noch nicht. „JPA“ gibt es also auch. Nun hoffen wir darauf, dass die Annotations aus dem Komentar verschwinden und im Code landen, so dass auch Parameter von Funktionen oder Methoden Anntotations haben können. Die Entwicklung in Java war die Gleiche. Alte Versionen von XDoclet basierten auch auf Annotation im Kommentar, weil es die Annotation im Code noch nicht gab.
Annotations dürfen meiner Meinung nach gar keinen Einfluss auf die Funktionen des Quellcodes haben.
1. Debugging fast unmöglich
2. performance-Technisch ein disaster
3. jQuery effekt: Keiner weiss was im Hintergrund passiert.
also ich persönliche finde das prinzip der Annotations dämlich da man als jemand der noch NIE mit den dingern gearbeitet hat denkt das is nur kommentar der einem sagt was da rein muss und dann ändert man oder kürzt es weg weil es ja „nur kommentar“ ist ich habe hier erst erfahren was annotations sind und ich hätte vlt in anderer PHP software diese vlt einfach weggekürzt da ich es eben bisher nicht kannte und dachte die vielen sterne waren nur um den comment besser zu markieren.
Genau! Und Groß-/Kleinschreibung und Interpunktion gibts auch nur, um Text lesbarer zu machen – völlig überflüssig also.