SitePoint Sponsor

User Tag List

Results 1 to 6 of 6
  1. #1
    SitePoint Wizard bronze trophy Jeff Mott's Avatar
    Join Date
    Jul 2009
    Posts
    1,311
    Mentioned
    19 Post(s)
    Tagged
    1 Thread(s)

    Annotations in PHP: They Exist

    I came across this gem just now. My first thought was, "138 slides?! Man, I don't have that kinda time." But it turns out it's a great presentation. Well worth a look.
    "First make it work. Then make it better."

  2. #2
    SitePoint Guru bronze trophy
    Join Date
    Dec 2003
    Location
    Poland
    Posts
    930
    Mentioned
    7 Post(s)
    Tagged
    0 Thread(s)
    Thanks for the link. However, I'm not a fan of using annotations for configuration. To me this article makes much more sense because it explains the why behind things. It's good that PHP has a reflection method to read annotations but using it for anything more than creating documentation seems like misuse. Let annotations annotate and that's it.

  3. #3
    SitePoint Addict bronze trophy Hall of Famer's Avatar
    Join Date
    Apr 2013
    Location
    Ithaca
    Posts
    368
    Mentioned
    6 Post(s)
    Tagged
    2 Thread(s)
    I am not a fan of annotations either, I like to write code than comments. But have to agree that they are helpful at times, so its always nice to keep them an option that they are available when you need them.

  4. #4
    SitePoint Wizard bronze trophy Jeff Mott's Avatar
    Join Date
    Jul 2009
    Posts
    1,311
    Mentioned
    19 Post(s)
    Tagged
    1 Thread(s)
    Quote Originally Posted by Hall of Famer View Post
    I am not a fan of annotations either, I like to write code than comments.
    I understand the hangup that comments shouldn't be code. Let's suppose, instead, that PHP formalizes annotations into the language (like Java, C#, and others have done). Such as...

    Code PHP:
    <?php
     
    <Entity("users")>
    class User
    {

    No comments anymore, so this ought to alleviate that icky feeling.

    Yet all we actually did was change the token used to denote an annotation. Were there any practical issues we solved by doing this? After all, docblocks were already treated specially. Internally, PHP already distinguishes a docblock from a comment. Opcode caches take docblocks into account, but ignore comments. Reflection also takes docblocks into account, but ignores comments.

    Maybe it's time we stop thinking of docblocks as comments and start thinking of them as a language construct. They already behave that way.
    "First make it work. Then make it better."

  5. #5
    SitePoint Addict bronze trophy Hall of Famer's Avatar
    Join Date
    Apr 2013
    Location
    Ithaca
    Posts
    368
    Mentioned
    6 Post(s)
    Tagged
    2 Thread(s)
    Well my idea is that annotation is just like comments. I dont consider them as actual code, since they are irrelevant to the language you are using. It feels like you are learning a markup language, it may be easier to learn than XML but it still does not feel as natural as writing code.

  6. #6
    SitePoint Guru bronze trophy
    Join Date
    Dec 2003
    Location
    Poland
    Posts
    930
    Mentioned
    7 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by Jeff Mott View Post
    I understand the hangup that comments shouldn't be code.
    [...]
    Maybe it's time we stop thinking of docblocks as comments and start thinking of them as a language construct.
    Actually, the comment-like syntax of annotations in PHP is the least serious problem. TomB mentions 7 reasons why they are bad and only the first one is alleviated by using a different (non-comment-like) syntax if such were available. Things like breaking separation of concerns and tight coupling are far more important here. They may seem convenient at first because of succinctness and keeping everything in one place but in the long run I much prefer my classes to be independent from configuration and doing stuff like defining dependency injection or validators via annotations is inflexible, requires learning a new metalanguage (or maybe a few) and feels just wrong.

    Edit:
    I've just learned there's a term Principle Of Least Astonishment that we should strive for, that is make the code as clear and obvious for other programmers as possible - and to me annotation meta-language magic effectively breaks the principle. I've found out a library whose author decided to use annotations for configuring DI and what I find most valuable are the comments here by other programmers who present very good reasons why this is a bad idea - I think this is a very good read and there's lots of sound wisdom in it.


Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •