13 ms·

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 a

by jawngee 14y ago

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.

risratorn 14y ago
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&s=annotations http://marc.info/?r=1&w=2&q=b&l=php-internals&#3... https://wiki.php.net/rfc/annotations https://wiki.php.net/rfc/annotations
- masklinn 14y ago
  > 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 14y ago
  Wow, I didn't know about those RFCs to make annotations a part of the language. Thanks for posting.
bertzzie 14y ago
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?
- masklinn 14y ago
  > 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 14y ago
    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 14y ago
      > 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 14y ago
        > 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...
bsmith 14y ago
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 14y ago
  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 14y ago
    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 14y ago
    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 14y ago
  > PHP also has a goto function. Should we use it just because we can? Definitely yes. Use it whenever fit.
SquareWheel 14y ago
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 14y ago
  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 14y ago
    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 14y ago
      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 14y ago
        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).
      - 14y ago
stevenwei 14y ago
It's kind of funny cause his proposed alternative is how Doctrine originally worked... http://docs.doctrine-project.org/projects/doctrine1/en/latest/en/manual/working-with-models.html http://docs.doctrine-project.org/projects/doctrine1/en/lates...
vojant 14y ago
Agree. Symfony and Doctrine 2 compile annotation to PHP anyway. I'ts much easier to use annotaions than xml or yamls configurations.
theunraveler 14y ago
> 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 14y ago
  verbosity.
colanderman 14y ago
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 14y ago
  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.
deleted 14y ago
[deleted]
zyb09 14y ago
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 14y ago
  give us a pointer to an example please.
  - tterrace 14y ago
    That's a silly thing to require a citation for unless you're unfamiliar with preprocessor directives.
    - prunebeads 14y ago
      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.
danso 14y ago
> ...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 14y ago
  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 14y ago
    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.
mikeash 14y ago
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?
- prunebeads 14y ago
  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 14y ago
    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?
    - Dylan16807 14y ago
      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 *@.
    - prunebeads 14y ago
      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.
drivingmenuts 14y ago
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 14y ago
  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.
adatta02 14y ago
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 14y ago
It would be pretty nice if PHP somehow slowly morphed into being about elegance, rather than becoming more and more horrible over time.
slurgfest 14y ago
"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 14y ago
  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.
Firehed 14y ago
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 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.php#94061 http://www.php.net/manual/en/reflectionclass.getdoccomment.p...
mcantelon 14y ago
Part of getting things done is having maintainable code. This type of craziness is completely unnecessary.

by jawngee 14y ago

risratorn 14y ago

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&s=annotations http://marc.info/?r=1&w=2&q=b&l=php-internals&#3... https://wiki.php.net/rfc/annotations https://wiki.php.net/rfc/annotations

masklinn 14y ago
> 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 14y ago
Wow, I didn't know about those RFCs to make annotations a part of the language. Thanks for posting.

bertzzie 14y ago

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?

masklinn 14y ago
> 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 14y ago
  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 14y ago
    > 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 14y ago
      > 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...

bsmith 14y ago

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 14y ago
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 14y ago
  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 14y ago
  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 14y ago
> PHP also has a goto function. Should we use it just because we can? Definitely yes. Use it whenever fit.

SquareWheel 14y ago

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 14y ago
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 14y ago
  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 14y ago
    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 14y ago
      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).
    - 14y ago

stevenwei 14y ago

It's kind of funny cause his proposed alternative is how Doctrine originally worked... http://docs.doctrine-project.org/projects/doctrine1/en/latest/en/manual/working-with-models.html http://docs.doctrine-project.org/projects/doctrine1/en/lates...

vojant 14y ago

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

theunraveler 14y ago

> 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 14y ago
verbosity.

colanderman 14y ago

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 14y ago
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.

deleted 14y ago

[deleted]

zyb09 14y ago

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 14y ago
give us a pointer to an example please.
- tterrace 14y ago
  That's a silly thing to require a citation for unless you're unfamiliar with preprocessor directives.
  - prunebeads 14y ago
    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.

danso 14y ago

> ...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 14y ago
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 14y ago
  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.

mikeash 14y ago

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?

prunebeads 14y ago
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 14y ago
  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?
  - Dylan16807 14y ago
    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 *@.
  - prunebeads 14y ago
    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.

drivingmenuts 14y ago

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 14y ago
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.

adatta02 14y ago

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 14y ago

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

slurgfest 14y ago

"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 14y ago
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.

Firehed 14y ago

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 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.php#94061 http://www.php.net/manual/en/reflectionclass.getdoccomment.p...

mcantelon 14y ago

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