Add documentation for AssignmentInTernaryCondition sniff#2488
Add documentation for AssignmentInTernaryCondition sniff#2488Nic-Sevic wants to merge 2 commits intoWordPress:developfrom
Conversation
rodrigoprimo
left a comment
There was a problem hiding this comment.
Thanks for working on this PR, @Nic-Sevic! I left some comments for us to discuss. Please take into account that I'm not a maintainer of the project so I might have missed something or suggest something that the maintainers might disagree.
WordPress/Docs/CodeAnalysis/AssignmentInTernaryConditionStandard.xml
Outdated
Show resolved
Hide resolved
WordPress/Docs/CodeAnalysis/AssignmentInTernaryConditionStandard.xml
Outdated
Show resolved
Hide resolved
WordPress/Docs/CodeAnalysis/AssignmentInTernaryConditionStandard.xml
Outdated
Show resolved
Hide resolved
| <documentation title="Assignment In Ternary Condition"> | ||
| <standard> | ||
| <![CDATA[ | ||
| Checks that variable assignment does not occur in conditional statement of ternary. Condition must be in parentheses to be checked; Ternaries lacking parentheses around condition are skipped. If incorrect will throw: "Variable assignment found within a condition. Did you mean to do a comparison?" |
There was a problem hiding this comment.
Checks that variable assignment does not occur in conditional statement of ternary.
Usually, the standard descriptions are quite explicit/directive. Similar to the error messages. So maybe instead of saying what the sniffs checks, I would suggest describing what the sniff expects. Something like:
"There should be no assignments in the condition part of ternary."
This might need some more polishing but should give the general idea. Checking other descriptions might help as well.
If incorrect will throw: "Variable assignment found within a condition. Did you mean to do a comparison?"
I believe that the sniff documentation usually does not include the error message displayed, so I suggest not including it here unless there is a reason to include it for this particular sniff.
There was a problem hiding this comment.
Tried to clarify standard description and improve readability
There was a problem hiding this comment.
Thanks for improving the description. I just realized that I misled you with the text I suggested. This sniff throws a warning and not an error, so we should not use should. Instead, we could say something like it is recommended or some other variation. Could you please update the description to account for that?
| ]]> | ||
| </standard> | ||
| <code_comparison> | ||
| <code title="Valid: Variable assigned with comparison in parentheses."> |
There was a problem hiding this comment.
This sentence seems a bit confusing to me because of the use of the word "assigned". The sniff is not about assigning the result of a ternary comparison to a variable. The sniff is triggered whether or not the result of the ternary is assigned to a variable. At the same time, the sniff is precisely checking if there is no assignment in the condition part of the ternary.
Maybe this could be rephrased to avoid this confusion? I also wonder if it would be better to include just the ternary without the echo and the assignment to variable in the examples.
WordPress/Docs/CodeAnalysis/AssignmentInTernaryConditionStandard.xml
Outdated
Show resolved
Hide resolved
WordPress/Docs/CodeAnalysis/AssignmentInTernaryConditionStandard.xml
Outdated
Show resolved
Hide resolved
rodrigoprimo
left a comment
There was a problem hiding this comment.
Thanks for improving this PR, @Nic-Sevic. It is looking good! I left some final comments for us to discuss before I approve it.
| > | ||
| <standard> | ||
| <![CDATA[ | ||
| Variables should not be assigned in conditional statement of ternary. |
There was a problem hiding this comment.
| Variables should not be assigned in conditional statement of ternary. | |
| Variables should not be assigned in the condition of a ternary operator. |
I believe it is more common to use "condition" instead of "conditional statement" to refer to the first expression of a ternary, but I could be wrong. Reference: https://en.wikipedia.org/wiki/Ternary_conditional_operator. I found no mention of "condition" or "conditional statement" in the php.net page about ternaries: https://www.php.net/manual/en/language.operators.comparison.php. We might need to update the text for the valid and invalid examples as well.
Also, the sentence reads better to me if the article "a" is added before "ternary". That being said, I'm not a native speaker, so let me know if that is not the case.
| <standard> | ||
| <![CDATA[ | ||
| Variables should not be assigned in conditional statement of ternary. | ||
| Condition must be in parentheses to be checked; ternaries lacking parentheses around condition are skipped. |
There was a problem hiding this comment.
| Condition must be in parentheses to be checked; ternaries lacking parentheses around condition are skipped. | |
| The condition must be in parentheses to be checked; ternaries lacking parentheses around the condition are skipped. |
Similar to the above, the sentence reads better to me if we add the article "the", but feel free to ignore this comment if that is not the case.
| <code_comparison> | ||
| <code title="Valid: Conditional statement in parentheses and does not include variable assignment."> | ||
| <![CDATA[ | ||
| $mode = ( $a <em>==</em> 'a' ) ? 'b' : 'c'; |
There was a problem hiding this comment.
| $mode = ( $a <em>==</em> 'a' ) ? 'b' : 'c'; | |
| $mode = ( $a <em>==</em> 'a' ) ? 'b' : 'c'; |
Just a nitpick, but usually, the code examples are not indented and should have no spaces. So, the initial version was correct. It doesn't have a noticeable impact in this case, and this is just a single line, but for multiple line code samples, it makes a difference.
| <code_comparison> | ||
| <code title="Valid: Conditional statement in parentheses and does not include variable assignment."> | ||
| <![CDATA[ | ||
| $mode = ( $a <em>==</em> 'a' ) ? 'b' : 'c'; |
There was a problem hiding this comment.
| $mode = ( $a <em>==</em> 'a' ) ? 'b' : 'c'; | |
| $mode = ( $a <em>===</em> 'a' ) ? 'b' : 'c'; |
This is another nitpick, but I suggest using a strict comparison instead of a loose comparison in the valid example so that it follows coding best practices.
|
@Nic-Sevic, I was just wondering if you'll have a chance to finish this off in the near future. It would be great if this PR could be included in the next WPCS release. If you haven't got time or lost interest, please let us know and we'll see if we can find someone to take over. Thanks! |
|
@Nic-Sevic, please let us know within a week if you are still interested in finishing this PR. If we don't hear back from you, we will presume you don't have time, and we will see if we can find someone else to take over and finish it. Thanks for your work so far! |
Related to #1722