4 ms·

The Named Parameters [0] are useful but there are editors that solves the problem in another way. Write a function with a docblock [1] on top of it and then mou

by Moru 5y ago

The Named Parameters [0] are useful but there are editors that solves the problem in another way. Write a function with a docblock [1] on top of it and then mouse over the function call and it shows you the documentation of the function with every parameters use. Or start typing the function name and autocomplete fills in the rest with parameter names and show the docblock above. Saves my sanity many times per day. [0] https://dnlytras.com/blog/modern-php/#Named-parameters https://dnlytras.com/blog/modern-php/#Named-parameters [1] https://docs.phpdoc.org/latest/guide/guides/docblocks.html https://docs.phpdoc.org/latest/guide/guides/docblocks.html

Beltalowda 5y ago
The obvious downside of this is that you're adding all these noisy "@param string $filename The name of the file." and "@return string The modified filename." comments. A lot of PHP projects are littered with this kind of stuff, and when there's actually some important comment it's easy to miss.
- Tijdreiziger 5y ago
  Isn't this a pretty generally accepted pattern? Java and Python use a similar format for their docstrings.
  - Beltalowda 5y ago
    It's okay-ish if you need to document that actually needs documenting, but if you use docstrings for typing/IDE assistance people will document every single thing for that, leading to useless "documentation" like in my previous comment. That said, I personally prefer just a paragraph or two of prose over "structured" formats.
    - paulryanrogers 5y ago
      Agree, I like to see at least an example value in the Docblock
deergomoo 5y ago
I think named parameters were a mistake for PHP. They weren’t really added for documentation purposes, but to avoid the situation where a function with n arguments with default values needs you to specify all the intermediate ones just to override a value at the end. They’re a great idea in languages designed with them from the start, but adding them to an existing language makes something that was previously a private implementation detail part of the public contract, and only for certain versions of the language. There are already packages that opt out of considering parameters names part of their semantic versioning, effectively demoting it to a “use at your own risk” feature. I would almost have preferred it to be added only as a special case for built-in features, which are almost all plain functions and have become somewhat unwieldy in places. Third-party code is more often than not object oriented, and so could easily lean on stuff like parameter arrays or fluent interfaces to avoid the ergonomic issues from having tons of parameters.
- conradfr 5y ago
  I would have preferred a "default" keyword. So given: function foo(string $arg1, int $arg2=2, string $arg3='reddit') {} You could called it like: foo('bar', default, 'HN');
Cyberdog 5y ago
As someone who played around a lot in Swift back in the day, I love named parameters and can't wait to be working on a project where I can use them (it will probably be a while). They really help the code stay self-documenting and solve the "Is it $haystack, $needle, or $needle, $haystack?" sorts of confusion.

by Moru 5y ago

Beltalowda 5y ago

The obvious downside of this is that you're adding all these noisy "@param string $filename The name of the file." and "@return string The modified filename." comments. A lot of PHP projects are littered with this kind of stuff, and when there's actually some important comment it's easy to miss.

Tijdreiziger 5y ago
Isn't this a pretty generally accepted pattern? Java and Python use a similar format for their docstrings.
- Beltalowda 5y ago
  It's okay-ish if you need to document that actually needs documenting, but if you use docstrings for typing/IDE assistance people will document every single thing for that, leading to useless "documentation" like in my previous comment. That said, I personally prefer just a paragraph or two of prose over "structured" formats.
  - paulryanrogers 5y ago
    Agree, I like to see at least an example value in the Docblock

deergomoo 5y ago

I think named parameters were a mistake for PHP. They weren’t really added for documentation purposes, but to avoid the situation where a function with n arguments with default values needs you to specify all the intermediate ones just to override a value at the end. They’re a great idea in languages designed with them from the start, but adding them to an existing language makes something that was previously a private implementation detail part of the public contract, and only for certain versions of the language. There are already packages that opt out of considering parameters names part of their semantic versioning, effectively demoting it to a “use at your own risk” feature. I would almost have preferred it to be added only as a special case for built-in features, which are almost all plain functions and have become somewhat unwieldy in places. Third-party code is more often than not object oriented, and so could easily lean on stuff like parameter arrays or fluent interfaces to avoid the ergonomic issues from having tons of parameters.

conradfr 5y ago
I would have preferred a "default" keyword. So given: function foo(string $arg1, int $arg2=2, string $arg3='reddit') {} You could called it like: foo('bar', default, 'HN');

Cyberdog 5y ago

As someone who played around a lot in Swift back in the day, I love named parameters and can't wait to be working on a project where I can use them (it will probably be a while). They really help the code stay self-documenting and solve the "Is it $haystack, $needle, or $needle, $haystack?" sorts of confusion.