The case for multiline signatures

Grégoire Paris on October 21, 2017

Hopefully, my last blog post convinced you to avoid long lines. The php community has a nice coding style guide called PSR-2 that says the follow... [Read Full]

I'm personally a fan of not using multiline signatures as they clutter a lot. However, this is only a thing when using interfaces. When using interfaces, you won't (often) change the signature either way.

When not using interfaces (like constructors or callables), it's a good idea to take a step back and wonder if you really need that many arguments. If you do, multiline. If you don't > refactor.

I think it should be completely okay to "clutter" an interface with signatures, because you are definitely not supposed to have many methods in an interface, see the ISP. Plus, even if you don't change them often, they should still be easy to read too, especially in the Github editor.

I didn't make this clear in my post, sorry about that.

Talking about interfaces, I mean the implementations thereof, not that actual interface. The signature in the interface is something important, whereas the implementation I couldn't care less about.

I voted a unicorn because it's you. :-)

Your old one line signatures' enemy will try to answer you. <3

Be prepared, you will be surprised for some parts. ;-)

Also, since php 7.0, function signatures are getting far more type hinting than before, which makes them longer, but also more useful, because they describe what type of variables you are dealing with.

This is true. This is not about a debate here, it's a fact.

Then remove the phpdoc, unless you wrote something very interesting in it.

Well, this is a little bit more complicated than that in my opinion. I'll try to explain clearly.

You are quite right, since php 7, most of the phpdoc type-hinting became duplicate and useless. But some only.
For basic type, they are, for sure. But for object, it could be more complicated. Sometime you have to specify some sub-classes on the phpdoc to get IDE completion working.

So you will tell me that we can only specify those special parameter. Well, it could be but two points:

  • It's quite weird to have only some parameter defined and some note. But maybe it's just an illusion
  • 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.

So now you will maybe tell me that in this case, we should put the phpdoc only when some parameters needs to be specified and nothing for the other.
It's an idea indeed, but here too I see two points:

  • It's not consistent. But you will say it's a matter of opinions. And guess what? You're probably right.
  • 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?

I'll conclude this part because the PHPDoc can be a good discussion for another article: At this time, I think both are great.

Framework X, which my library uses, forbids multiline signatures
You should strive to make your library framework-agnostic, and segregate it from framework-integrations layers.

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

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.

And, as 99% of our projects are Symfony bundles, it makes sense to follow SF standard.

We have indeed some necessary exceptions, like short array for example. Yeah, no need to tell me, I opened a trolling hole here. :-D


Beside the comment I did, it's a great article. Really. And I agree especially for that point: PHP 7 type hinting give us more flexibility and force us to get new reflection and debate about multi-line signature and the usage of PHPDoc.

Also one concern for my case: 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? :-)

Best regards.

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.

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

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

Maybe it can be improved, but not removed.

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

code of conduct - report abuse