3 ms·
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." c
by 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 agoIsn't this a pretty generally accepted pattern? Java and Python use a similar format for their docstrings.
- Beltalowda 5y agoIt'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 agoAgree, I like to see at least an example value in the Docblock