PHP Annotations Are a Horrible Idea

Having used both doctrine and used a format of array mappings, I prefer the doctrine way of using annotations.

However I do also acknowledge that putting important information into comments can be somewhat dangerous. Doctrine does support storing metadata in yaml and xml files too, but in that case you need to ensure that changes to your model class get reflected in the mapping file.

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?

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

  
  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.

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.

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