[jawngee]

This is pure horse pucky.

First of all PHP isn't about elegance and I find it a teeth grinding experience when people complain about it not being so. PHP is about getting stuff done.

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. "Reliance on Yet Another Library"? C'mon.

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

Also, his alternatives are kind of weak. Here's an annotation:

    /**
     * @Column(type="string", length=32, unique=true, nullable=false)
     */    
    protected $username;

And here's his proposed alternative:

    class User
    {
        public static $mapping = array(
            'username' => array(
                'type' => 'string',
                'length' => 32,
                'unique' => true,
                'nullable' => function() {
                    // Some logic to determine value.  
                }
            )
        );  
    }

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

[bsmith]

I disagree.

> 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.

[Sumaso]

Many of the OPs complains have the tone of "not my PHP!!!".

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)

[theunraveler]

I am not opposed to change--in fact, I welcome it, especially with regard to PHP. Rather, I'm criticizing the use of annotations based on the argument that it is bad application design.

[astrodust]

Making comments become as important as live code is never a good idea. This practice also encourages arbitrary syntax and would eventually lead to a mess of different standards with no cohesion.

Having a proper `pragma` declaration would be ideal.

[hrktb]

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

Definitely yes. Use it whenever fit.

[colanderman]

Here's a good, valid, technical reason: any meta-programming tool – even a well-designed one – that strips out comments will now change the meaning of your code and silently fail.

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.

[tomcorrigan]

Please provide an example of such a tool for PHP. Also provide a working example of PHP code where removing all annotations causes working code to fail silently. In my experience with using annotations in PHP if the annotations are missing/invalid the compiling code throws very descriptive error messages.

Your good, valid, technical reasons are anything but.

[drivingmenuts]

Any editor that starts with comments collapsed is going to hide the functionality buried in comments. But that's a minor issue.

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.

[Osiris]

The examples in the annotations RFC that he links to actual use C# style attributes syntax:

  <Attribute(Value)>
  public class Sample { }

I think that's a better approach as it makes the annotations an actual language construct and keeps them out of comments.

[bertzzie]

I think this is quite a good technical reason:

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

In which other language do you see comment is necessary to make the code function properly?

[btilly]

In which other language do you see comment is necessary to make the code 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.

[masklinn]

> In which other language do you see comment is necessary to make the code function properly?

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.

[bertzzie]

I never know that, but still, the point stands: making a comment necessity for code to function properly is bad, bad, bad. That's why the Java folks throws it out right?

[masklinn]

> I never know that, but still, the point stands: making a comment necessity for code to function properly is bad, bad, bad.

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.

[bertzzie]

> 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...

[masklinn]

> 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".

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.

[chaosfox]

Its a syntax problem then ? what if the annotation wasn't inside comments would that make it ok ?

[bertzzie]

I think yes. It's ok if it's not inside comments. Just like any other language (I know at least C# and Java do this for example).

[astrodust]

A lot of this boils down to PHP's feeble "array" declarator. Take a page from JavaScript and make it easy.

[mark_story]

As of PHP 5.4 you can use [] to define arrays. It saves some typing, and is less noisy on the eyes I guess.

[astrodust]

That's exactly the way it should be. Hopefully this will become the standard before long.

[SquareWheel]

    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.

Maybe it is subjective, but it sure gives me an icky feeling. You're breaking down a clear division between code and comment - fuzzing the lines. There's something about the idea that yes, I can only describe as being gross.

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

[prunebeads]

Some people don't like 4 space indentations, some don't like using tabs, and in most cases there's just an icky feeling behind it. Who's right?

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?

[mercurial]

You can be intuitively against something, but not be able to work out why. A few hours later, you often realize the rational reasons behind your original feeling.

[prunebeads]

Indeed, but what if you don't? I'm not saying that intuition is bad. I'm saying that intuition is bad when trying to make a reasonable point.

[SquareWheel]

I'd agree with that, good insight.

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).

[mercurial]

Sure. I read it as "there is something wrong with it, but I can't pinpoint what", which is fair enough in my book. It's not like this is the lynchpin of the article.

[prunebeads]

It's noise in disguise to me: filler to make it look like he has more arguments than he really has.

[mikeash]

If annotations are in comments, how are you going to leave actual comments containing annotations that you don't want to actually affect the code?

[tomcorrigan]

Easily, the annotation parser ignores all comments that it doesn't recognise.

    /**
     * @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;

[prunebeads]

by escaping them?

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.

[mikeash]

So now you have a system for putting comments inside your comments? Are you going to eventually start putting meta-annotations inside your meta-comments, and inventing meta-meta-comments so you can comment on the meta-annotations?

[prunebeads]

Actually, no. What I have now is comment blocks which may contain normal annotations and escaped ones. There's no need to go deeper in meta-meta-something.

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.

[Dylan16807]

So now you have a system for putting quotation marks inside your strings? Are you going to eventually start putting escaped-quotation marks inside your escaped-quotes, and inventing escaped-escaped-quotation marks so you can quote the quoted-quotation marks?

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 *@.

[conradfr]

By not using / * * to start your comment block ?

[mikeash]

If you're going to have different syntax for annotations and actual comments, why not choose a syntax that's properly different and not just a weird mutation?

[robryan]

Because they want something that is still valid PHP.

[mikeash]

But why? Do I misunderstand that these annotations change the meaning of the code? Why would you want something that's still valid PHP without them, but means something else?

[zyb09]

It's really bad practice. We all want to get stuff done, but don't complain when you end up in spagethi code hell. Some people are going to see that and think that's an ingenious use of comments, and then start to do the same in everything they write soon after. If you ever seen Preprocessor abuse in C++ you know what I mean.

[prunebeads]

give us a pointer to an example please.

[tterrace]

That's a silly thing to require a citation for unless you're unfamiliar with preprocessor directives.

[prunebeads]

Some people may not be familiar with C macros, and an example could help grasp the problem you're talking about.

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.

[stevenwei]

It's kind of funny cause his proposed alternative is how Doctrine originally worked...

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

[risratorn]

the official RFC for annotations is actually a little cleaner in syntax, easier to read and implemented in the language itself which is a way beter system than comment annotations. On a level I do agree that docblock comments are no place for annotations, it's the best we can have for now though, just until annotations become a native PHP feature.

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&#3... https://wiki.php.net/rfc/annotations

[masklinn]

> the official RFC for annotations is actually a little cleaner in syntax, easier to read and implemented in the language itself which is a way beter system than comment 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.

[theunraveler]

Wow, I didn't know about those RFCs to make annotations a part of the language. Thanks for posting.

[danso]

> ...because I have other shit I need to do.

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

[randomdata]

To be fair, writing meaningful comments is really hard. So hard that the number of people who do it well is a small fraction of even the otherwise best programmers. To make matters worse, poor comments are worse than no comments at all. I can see why many programmers shy away from them.

* 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;

I am one of those poor commenters, so I really have no idea what could be said about that line that isn't already known. If you say not everything needs to be commented, then where does the line get drawn? In most cases, the vast majority of your code should be no less obvious than this.

* 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?

[astrodust]

Comments regarding methods should be added to clarify how they are intended to be used, and what the results should be expected to be.

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.

[randomdata]

I would love to see a good example of your first case. It is difficult to imagine and learn from it without seeing it action.

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.

[astrodust]

I find it's best to describe what the argument are, as short names are rarely enough, and the return values or values supplied to callbacks under various conditions.

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.

[randomdata]

Wouldn't that kind of information be better expressed in machine-human-readbale formats outside of the code that can be used to not only convey the information to the reader, but also verify that the description does as it says it does?

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.

[theunraveler]

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

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

[prunebeads]

verbosity.

[Firehed]

The reflection tools aren't meant for constant run-time use.

"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...

[vojant]

Agree. Symfony and Doctrine 2 compile annotation to PHP anyway. I'ts much easier to use annotaions than xml or yamls configurations.

[slurgfest]

"PHP is about getting stuff done."

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.

[Firehed]

I think it was intended to mean that it eschews some advanced/clever functionality in favor of having a shallow learning curve. That doesn't make it the best tool for the job (nor does it prevent it from being so), but it implies that you can get started on solving your problem in thirty seconds rather than having to spend two hours prepping your dev environment and web stack any time you want to make a change.

[adatta02]

Your second example is actually how Doctrine 1.2+ works. You could define your models in a YAML file which was then transformed into PHP classes at runtime.

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

[code_duck]

It would be pretty nice if PHP somehow slowly morphed into being about elegance, rather than becoming more and more horrible over time.

[mcantelon]

Part of getting things done is having maintainable code. This type of craziness is completely unnecessary.