DEV Community

Discussion on: The case for multiline signatures

Collapse
 
greg0ire profile image
Grégoire Paris

Great answer thanks!

Let me address a few of your points:

So you will tell me that we can only specify those special parameter

Indeed, I will

On most of the IDE, the developer will use phpdoc generation and will be good with that. But yeah, you will have the other typing. Should we annoy the contributors to remove the useless part? I think not.

The typing is far, far more reliable than the comments. IDEs should strive to use the former if they do not already. Comments rot, and are often wrong, as phpstan shows.

Should we annoy the contributors to remove the useless part? I think not.

And I think they can take it. Not a big deal if they themselves feel that the comments are a bit redundant, which they very often are.

Well, I think you will lie if you deny to talk about Sonata Project as an example. :-)

Not only! Api-platform gives the same reason when asked, but yeah, Sonata is of course the example I had in mind, but I didn't want to point fingers (except for Magento :P)

Hoomans may support non-consistency, linters will not. If we want to have more control on that, how to determine when to make or not to make a phpdoc with a bot?

A bot can hardly determine if a parameter needs a comment, since now the typing is described, all there is to describe is non-obvious behaviors, which you cannot know about unless you understand the code.

I don't totally agree with your argument. For the case of Sonata, we don't have a lot of time maintaining the repositories and I really think following a big standard is give more benefices than define our own.

We have linters to cherry-pick the rules we want. We could do that once and for all, and that wouldn't be a big deal. The Symfony standard minus the rules we don't like could be great.

Beside the rule you choose (multi or single line), I think this should apply every where, like the , for the multi-lined arrays. You know, for git conflicts? :-)

I don't think we should go that far, even if that kind of stuff can indeed be the source of some conflicts.

Collapse
 
soullivaneuh profile image
Sullivan SENECHAL

The typing is far, far more reliable than the comments. IDEs should strive to use the former if they do not already. Comments rot, and are often wrong, as phpstan shows.

I'm not talking about IDE relying, but comment generation. ;-)

Thread Thread
 
greg0ire profile image
Grégoire Paris

I think that feature is now useless and should be removed. It just empowers devs to generate what often ends up being useless noise.

Thread Thread
 
soullivaneuh profile image
Sullivan SENECHAL

Maybe it can be improved, but not removed.

Otherwise, I'll just use ed. :-P