In the last code block, when the page is initially loaded, we have lines 20-62 hidden. Then you click arrows and have lines 20-41 hidden. Then you click arrows again and have no more lines hidden. But that is not true! Line 20 is still hidden, but no arrows - one has to click the square on the top of the code block.
How did I found this bug? I wasn't into context of the tutorial because I only needed to check one thing out and I didn't remember that you were using TargetPathTrait in your Helper. I just needed to check something in the section "Making the Class final". So I scrolled down to investigate this one code block and I couldn't figure out where the hell are saveTargetPath() and getTargetPath() coming from. Maybe he used a trait? No, there is no trait. And after few minutes I recognized the line 20 was missing.
Ah, we're sorry about this! And yeah, good catch, it looks like a bug! Thanks for reporting it, we'll take a look at it soon. For now, as a workaround, you can expand ALL lines by clicking on squared icon in the left top corner of the code block.
Ryan says: "Oh, and, thanks to the string type-hint, the @param documentation is totally redundant and should be removed."
Isn't it against Symfony Coding Standards which say: "Add PHPDoc blocks for all classes, methods, and functions (though you may be asked to remove PHPDoc that do not add value);"
Ah, you have a close eye - nice work :). I think what the docs are saying and what I'm saying are 2 ways of "trying to explain the same thing". When I say:
the @param documentation is totally redundant and should be removed
I didn't meant to imply that all @param documentation is redundant, just that specific @param. Especially with scalar type-hints, if you type-hint an argument, and the name of the argument makes it very obvious what the purpose of that argument is, then adding something like @param string $name does not "add value" (as the Symfony docs say). However, if the argument truly needs some more explanation - e.g. @param string $providerKey The name of the firewall that is currently being used - then the @param DOES add value and should be included.
The point is: question whether or not something adds value or not. We typically think that all documentation adds some value. But because Symfony is such a large codebase, docs also add extra overhead (e.g. future pull requests to do simple things like re-word those docs, or add punctuation) - so the docs really need to add value.
After few days of having this standard in back of my head, I think I've misunderstood (however my interpretation makes sense when to think about it) the word "though" in the context of the sentence. I thought I should add phpdocs THOUGH I may be asked (by something, eg. IDE or someone, eg. developer who doesn't follow standards) to remove the ones that do not add any value (so ignore those questions and add dockblocs anyway). Now I can see I should add phpdocs HOWEVER I may be asked (eg. by Symfony Team member) to remove the ones that do not add any value (which leads to not to add this docsblocks at first so nobody should ask me to remove it after I make pull request).
Sometimes, the same sentence means something different in different days :)
Please, log in to vote for this comment
|
Share Comment
"Houston: no signs of life" Start the conversation!
The concepts in this tutorial work great for Symfony 5!
5 Comments
Is is a bug?
In the last code block, when the page is initially loaded, we have lines 20-62 hidden. Then you click arrows and have lines 20-41 hidden. Then you click arrows again and have no more lines hidden. But that is not true! Line 20 is still hidden, but no arrows - one has to click the square on the top of the code block.
How did I found this bug? I wasn't into context of the tutorial because I only needed to check one thing out and I didn't remember that you were using TargetPathTrait in your Helper. I just needed to check something in the section "Making the Class final". So I scrolled down to investigate this one code block and I couldn't figure out where the hell are saveTargetPath() and getTargetPath() coming from. Maybe he used a trait? No, there is no trait. And after few minutes I recognized the line 20 was missing.
Hey Alexane,
Ah, we're sorry about this! And yeah, good catch, it looks like a bug! Thanks for reporting it, we'll take a look at it soon. For now, as a workaround, you can expand ALL lines by clicking on squared icon in the left top corner of the code block.
Cheers!
Ryan says: "Oh, and, thanks to the string type-hint, the @param documentation is totally redundant and should be removed."
Isn't it against Symfony Coding Standards which say: "Add PHPDoc blocks for all classes, methods, and functions (though you may be asked to remove PHPDoc that do not add value);"
How shout I interpret this?
Hey Marcin!
Ah, you have a close eye - nice work :). I think what the docs are saying and what I'm saying are 2 ways of "trying to explain the same thing". When I say:
I didn't meant to imply that all @param documentation is redundant, just that specific @param. Especially with scalar type-hints, if you type-hint an argument, and the name of the argument makes it very obvious what the purpose of that argument is, then adding something like
@param string $namedoes not "add value" (as the Symfony docs say). However, if the argument truly needs some more explanation - e.g.@param string $providerKey The name of the firewall that is currently being used- then the @param DOES add value and should be included.The point is: question whether or not something adds value or not. We typically think that all documentation adds some value. But because Symfony is such a large codebase, docs also add extra overhead (e.g. future pull requests to do simple things like re-word those docs, or add punctuation) - so the docs really need to add value.
I hope that clarifies - very good question!
Cheers!
Thanks Ryan!
After few days of having this standard in back of my head, I think I've misunderstood (however my interpretation makes sense when to think about it) the word "though" in the context of the sentence. I thought I should add phpdocs THOUGH I may be asked (by something, eg. IDE or someone, eg. developer who doesn't follow standards) to remove the ones that do not add any value (so ignore those questions and add dockblocs anyway).
Now I can see I should add phpdocs HOWEVER I may be asked (eg. by Symfony Team member) to remove the ones that do not add any value (which leads to not to add this docsblocks at first so nobody should ask me to remove it after I make pull request).
Sometimes, the same sentence means something different in different days :)
"Houston: no signs of life"
Start the conversation!