Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

PHP Annotations Are a Horrible Idea

theunraveler.com

Post reply on HN
Print view View original

111–120 of 127 posts

Re: PHP Annotations Are a Horrible Idea

#111

Post by mercurial »

prunebeads wrote: post #97
mercurial wrote: post #88

Earlier quoted context omitted.

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.

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.

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.

Re: PHP Annotations Are a Horrible Idea

#112

Post by gview »

First of all, annotations are nothing new. They have been around in Java for years, and it was emulated because it had advantages that really don't need to be regurgitated by me. If they weren't a good idea, they wouldn't have lead to a formal adoption inside the language.

Secondly, in both Symfony2 and Doctrine2, annotations are an OPTION. You use them if you want to use them, and if you don't want to, you can use traditional configuration files. It doesn't seem that the author has done anything with either Symfony2 or Doctrine2, or he would have understood that. As someone who used Symfony1, ZF1, Propel and Doctrine, I would not go back to the old way of doing things, even if I was offered good money to do so (as happened just last week in fact).

Most people who actively use these components LOVE annotations, because they allow you to keep the configuration close to the code, and reduce verbosity.

They drive code generation, and reduce the amount of code that has to be written to get a specific job done. So if there's a problem debugging, is it really about annotations, or about code generation, and if we can't have code generation (facepalm) then I suppose we shouldn't have template systems like smarty or twig, simply because "debugging is harder" and editors have more work to do.

If it's not the author's cup of tea, nobody is forcing anyone to use these capabilities. Needless to say, I couldn't disagree with the premise of this article more. @jawngee already provided a simple salient example.

Re: PHP Annotations Are a Horrible Idea

#113

Post by astrodust »

randomdata wrote: post #110
astrodust wrote: post #107

Earlier quoted context omitted.

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…

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…

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.

Re: PHP Annotations Are a Horrible Idea

#114

Post by randomdata »

astrodust wrote: post #113
randomdata wrote: post #110

Earlier quoted context omitted.

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…

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 acco…

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.

Re: PHP Annotations Are a Horrible Idea

#115

Post by prunebeads »

mikeash wrote: post #71
prunebeads wrote: post #70

Earlier quoted context omitted.

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.

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?

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.

Re: PHP Annotations Are a Horrible Idea

#116

Post by hrktb »

bsmith wrote: post #14
jawngee wrote: post #5

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 tha…

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 wh…

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

Definitely yes. Use it whenever fit.

Re: PHP Annotations Are a Horrible Idea

#117

Post by robryan »

mikeash wrote: post #79
conradfr wrote: post #75

Earlier quoted context omitted.

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

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?

Because they want something that is still valid PHP.

Re: PHP Annotations Are a Horrible Idea

#118

Post by mcantelon »

jawngee wrote: post #5

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 tha…

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

Re: PHP Annotations Are a Horrible Idea

#119

Post by mikeash »

robryan wrote: post #117
mikeash wrote: post #79

Earlier quoted context omitted.

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?

Because they want something that is still valid PHP.

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?

Re: PHP Annotations Are a Horrible Idea

#120

Post by tomcorrigan »

colanderman wrote: post #42
jawngee wrote: post #5

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 tha…

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.

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.

Post reply on HN