> First of all PHP isn't about elegance...PHP is about getting stuff done.

What language isn't about getting stuff done?

> He doesn't offer one good valid technical reason why not to use comments...

Not true. The OP explicitly points out that it breaks many PHP debugging capabilities.

> The fact that you can even parse out comments with the reflection API lends, to me, that meta-programming is a-ok.

So what? PHP also has a goto function. Should we use it just because we can?

> I'll take the first one because I have other shit I need to do.

Just because it's less verbose doesn't mean it's better. Otherwise, everyone would use Coffeescript instead of JS.

If old PHP devs learn to look for annotations, points 2 and 4 no longer apply, and many points in 1 no longer apply either.

It sounds more like a PHP dev grumbling about change... (what else is new)

Having a proper `pragma` declaration would be ideal.

Definitely yes. Use it whenever fit.

If the annotation were instead, say, not inside the comments, then any such tool would either (a) leave the annotation intact, or (b) fail with an error when it encounters the unknown syntax.

Your good, valid, technical reasons are anything but.

Comments are exactly that - comments. They are not intended to be executed and can be changed or removed at will. They are not necessary. They exist to provide further explication for code that is not self-documenting (or just plain programmer wankery).

This changes the deal. This means that some comments are required without providing clear boundaries to those who are not cognizant of the new convention.

PHP would be better served by adding naked @annotations and leaving comments to be non-parsed.

  <Attribute(Value)>
  public class Sample { }

    Because code comments should never be necessary for a script to function properly. 

Oracle SQL hints come to mind: http://www.dba-oracle.com/t_sql_hints_tuning.htm

There is it even worse because the hint may be needed to make your code run, but Oracle doesn't tell you whether or not the hint is actually in use or made a difference.

If by "language" you mean "some library which also provides a separate but way more painful and verbose way of doing the same thing", then it existed in Java before Java 5 added annotations to the language itself.

Not really.

> That's why the Java folks throws it out right?

I'm not sure what that's supposed to mean. "Java folks" don't throw anything out, Sun introduced a better and better-supported mechanism for doing what javadocs were coerced into doing.

I mean the Java community didn't use it anymore, because the "annotation inside comment" thing is worse than "annotation supported natively by the language". Granted, it's the only practical way to do it in PHP for now, but it still didn't change the fact that it's bad, IMO.

I wonder why SensioLabs (the creator of Symfony and Doctrine) didn't make the PHP's annotation RFC into reality. They are a quite huge powerhouse in the PHP world...

Sure, unless you don't have "annotations supported natively by the language".

> Granted, it's the only practical way to do it in PHP for now

Indeed.

> I wonder why SensioLabs (the creator of Symfony and Doctrine) didn't make the PHP's annotation RFC into reality. They are a quite huge powerhouse in the PHP world...

They might be a powerhouse, but they still aren't the drivers of PHP itself, Zend is. They can ask for the RFC to be finalized and implemented but at the end of the day, they also need to ship. And probably to ship on more versions than a hypothetical future 5.5.

Mostly incorrect, these are javadoc annotations which usually aren't used by code (aside from the javadoc extraction tool that is, and sometimes code editors for the @deprecated javadoc tag)

Since java 5, java has notations as language syntax e.g.

    /**
     * Some javadoc comment
     */
    @Annotation
    public void someMethod() {
        // stuff
    }

Before java5, these were inside comments (alongside javadoc tags), fully processed by third-party tools and had no support from the JVM itself.

    He doesn't offer one good valid technical reason why not to use comments for meta-programming PHP other than "it just feels wrong" and an "icky feeling" which is entirely subjective.

To each their own I guess, but it's not something I'd allow in one of my projects.

In your own post, you give a reason for why you think (and not feel) it is wrong, and that's the right way to do. Icky feelings aren't. Maybe people saying that it feels wrong are crossing a line too?

Though I did make one (hopefully reasonable) point that it fuzzes the lines between code and explanation of that code, which I don't care for. The article also gives a valid reason that tools are not expecting this and won't correctly accommodate (though that could be considered a short-term problem).

    /**
     * @var integer $id
     *
     * @ORM\Column(name="id", type="integer")
     * @ORM\Id
     * @ORM\GeneratedValue(strategy="AUTO")
     * some comment that the doctrine parser will ignore completely
     */
    private $id;

Some annotations are meant to affect the code, some aren't. Those who do and need to be given as pure comments need to be escaped.

Regarding the comment inside comment system, if it were possible to have nested comments, it wouldn't be a problem anymore :). Since it's a Symfony convention, one could simply count the number of stars at the beginning of a comment line to know the meta-comment depth level. BTW, I know that you are being sarcastic here.

Anyway, this is beside the original problem. Annotations in comments are a problem, granted, but somewhat limited. It's easier and faster for a parser to look for comments and then annotations in them, rather than parse the whole PHP grammar augmented with annotations. Especially in PHP.

In other words, there is no need for some kind of elaborate escapes-upon-escapes method here, all you have to do is not start a comment line with *@.

You could have pointed out all the things that are done in the C obfuscation code contests, to illustrate your point, but maybe this is silly. Also, you start your point from the spaghetti code hell that C macros let people fall into (I guess you where thinking about #ifdef conditionals), but I don't see how annotations could generate that problem. Imho, your point is flawed.

C macros are useful, and when not misleadingly used, very effective at abstracting things in order to get the important structures apparent. That is what annotations attempt to provide. Regarding PHP annotations, the problem here is that it's difficult and time consuming to parse a PHP script, whereas comments are an easy target. SensioLabs went the easy road, perhaps also in the hope that someday annotations would find their way in PHP, and people would just have to remove the comments around them to be compliant.

http://docs.doctrine-project.org/projects/doctrine1/en/lates...

Judging from the RCF and discussions on internals we still have a long way to go before we get annotations in PHP core.

http://marc.info/?r=1&w=2&q=b&l=php-internals... https://wiki.php.net/rfc/annotations

Sure, everybody knows that, but when the language does not have actual annotations yet (in whichever form they are), in-comment annotations are a very common choice. That's also what Java libs tended to use before annotations were added in Java 5.

Ironically, that's often also the attitude of programmers who don't use comments in their code (in any language).

* Comments that describe what the code does are a complete waste of time. The code already tells you what it does.

* Comments that describe why the code was written has more merit, but I cannot see how the following is any real improvement over the first point:

  // Investments of this type have always added the interest
  // to the principle. Who are we to question convention?
  $balance = $principle + $interest;

* Some suggest the method signature and invariants should be documented, but that seems like just another exploitation of comments to deal with limitations of the language and is no better than putting annotations in the comments.

* I've seen code examples for using a given method in the comments, but that is better left to your test suite. Not only then can the reader see the example, but you can verify your method works at the same time without cluttering up the original codebase to boot.

If you are doing something weird, then yes, I am with you that comments are a big deal. However, if you are doing weird things on a regular basis I have to question your reasons for doing so. You shouldn't have to do weird things 99% of the time.

With that, teach us wise one. How can we all become great commenters so that we do not have to brush it off as something we do not have time for?

Comments within the code should be used to highlight things that are not what they seem. They should answer any "WTF?" questions that naturally arise. A typical example is something like "Hack: Need to pass fifth argument as -1 to avoid crash in broken library".

Comments that act like descriptive audio are useless.

As I mentioned before, it seems the number of people who can actually pull off good comments are exceedingly small. I've looked at some prolific open source projects that have a decent amount commenting around method definitions as you suggest is good practice, but found the comments to be no more enlightening than just looking at the source code itself. I will assume they were just poor examples.

I do agree with everything else you said though.

An example would be:

"Verify account takes an account ID, an optional enabled flag which, if specified, will only search for accounts that have a matching enabled status. The default is to search against all accounts. The return value is true if the account is valid, false otherwise."

These are extremely important in loosely typed languages where there is little indication as to what constitutes an acceptable argument. In a more rigid language like C++ there are usually a lot more hints in the language about what the input and output is.

Still, in programming "by contract" it is important to manage expectations and comments can communicate a lot of this.

I will agree that some of that information is worth writing down, but I'm not yet convinced a comment within the code is the right place for it.

> These are extremely important in loosely typed languages where there is little indication as to what constitutes an acceptable argument.

Isn't that just pushing language "flaws" into the comments, not unlike annotations are being used here? I'll grant you that it is pragmatic when faced with lack of tools, but the grandparent suggested annotation comments were a bad idea but comments were a great idea, which seems contradictory to me in light of this.

Remember that comments and documentation are no substitute for proper testing that will expose usage errors. No amount of machine readable specification can prevent this, so it's often a waste of programmer time to produce.

Which is pretty much what I was getting at. Consider the following pseudo-code:

  Verify account takes an account ID, an optional enabled flag which, if
  specified, will only search for accounts that have a matching enabled
  status. The default is to search against all accounts. The return
  value is true if the account is valid, false otherwise.:

    account = new Account(id: 1)
    assert account.search does_not_include id != 1

(I'm not sure that code even matches what your comment describes, but I couldn't really figure out what the comment was supposed to really intend the code to do, which brings me all the way back to my original points. Sorry.)

Uhh, what's so hard about making an array?

"PHP 5 comes with a complete reflection API that adds the ability to reverse-engineer classes, interfaces, functions, methods and extensions. Additionally, the reflection API offers ways to retrieve doc comments for functions, classes and methods." [1]

It's an awesome way to generate automatic documentation for big projects. Of course it's possible to use it for other stuff like pointing to a template (though I'll point out that it can be done faster and more obviously by replacing it with a single function call at the end of the method), but "right tool for the job" and all that.

There's a very widely understood premise in programming that comments are blocks of text in source code files intended only to be read by humans and have no effect on program execution. When you change the semantics of something so well-defined... God help you.

Also worth noting in your sample code is that many ORMs simply query the DB for the schema and cache that result, so you don't need either of those. Merely being able to connect to your database is sufficient. The former comment (@Column) is a nice, short, human-readable format so developers can see what a column is, but having your code execution depend on that is crazy. What happens if someone minified [2] the code? Or ran it through a bytecode accelerator [3]?

I'm not going to stop anyone from abusing comments in their own codebase, but I sure as hell won't let this behavior infect mine.

[1]: http://www.php.net/manual/en/intro.reflection.php [2]: Yes, I know that's pointless in server-side source code - doesn't stop it from happening. [3]: http://www.php.net/manual/en/reflectionclass.getdoccomment.p...

This implies that the road not taken by PHP (and thus the roads taken by other languages) are somehow unproductive. That's not accurate. Most languages are about getting stuff done. A tool can be explicit, or elegant, or whatever, and also help you get stuff done.

You are basically saying that PHP's design is at a global maximum for productivity and this is simply not true.

That of course, leads to the issue of having your configuration separate from your implementation/code.