I think we need to create a new codestyle rules for yii3 version

Yii 3.0 Design discussions
1

Form me:

  1. Align parameter/property names
  2. Align tag comments
    Like this
/**
 * This is a sample function to illustrate additional PHP formatter
 * options.
 *
 * @param        $one   The first parameter
 * @param int    $two   The second parameter
 * @param string $three The third parameter with a longer comment to illustrate wrapping.
 *
 * @return void
 * @author  J.S.
 * @license GPL
 */
function foo($one, $two = 0, $three = "String")
{
}

Why? Read like this code more easer.

2

If you add $fourth param, you need to realign all other params in phpdoc. The same if you change type from string to string|null. Or change param name. It is really annoying at long run - generates unnecessary conflicts and messing up with git history.

And for params with long description (or long types) aligning decreases readability.

7 Likes
3

I am against aligning. It unnecessarily messes diff up.

1 Like
4

I agree with the argument about diff/git.
But how often do you change the function/class interface? And how often do you read the code?
If we look at Symfony or Laravel libs we can see that to read easier.
We type code(I mean with codestyle) for us, not for a machine.

5

Honestly, I never considered this as a readability issue. If you want to check single param documentation, then it is quite obvious where to find type/name/description, and I’m not sure how adding a random number of whitespaces may help here. Yes, it may look nice if you take a look at an aligned list of params, but “nice” is not the same as “readable”.

1 Like
6

Why do you want to add whitespaces for function with single param?
From your words, you can read easy and fast table information without alignment the same as with alignment.
Am I right?

7

I never said that. I said that if I want to read documentation of only this one param (ignoring all other), these whitespaces are just noise. And number of whitespaces depends on completely irrelevant factor in context of this param (why length of param $three should affect number of whitespaces in param $one?).

No. I think that aligning does not improve readability at all, while it may reduce it in some cases.

8

Thanks for the explanation. I appreciate that.
What about my proposal - I think that it can’t be acceptable in this time. Maybe in the future. Maybe not. It doesn’t matter.

It was helpful for me. Now I understand Yii.

9

Well, yes, it’s nicer to read - but it’s also much more work, space for description may shrink and it may cause changes where nothing really changed.
So I would make it a “MAY” at best (if at all) - but not SHOULD or MUST.

10

In your own applications you’re free to use any code style that suits you well. For now I suggest PSR-2. When PSR-12 will be accepted, I’d suggest that one instead.

11

Since we’re going to start type hinting parameters anyway, you can also just leave out the types in the @param lines…

1 Like
12

Yes. That could be a good change.

13

That’s right!

And if you choose a good names for a param then you don’t need the @param tag at all. We have found this makes the code much more readable.

If you do a really good job writing the code and choosing names then you don’t need the docblock at all because the method signature says everything you need.

1 Like