I love writeups like this, and enjoyed the level of detail Colin provided.<p>I take away a different lesson, though: even simple web security is easy to get wrong, even for a very smart, very talented developer. I'm not sure what the solution is, though.<p>As for the comments, while I don't take a hard line here, I agree with Bob Martin's quote: "Every time you write a comment, you should grimace and feel the failure of your ability of expression." Wherever possible, you are better off rewriting the code and variable names to clarify <i>in the code itself</i> whatever you wanted to say in the comments. It's hard to say how to accomplish that here without knowing more about the code, though. And it may have been so difficult that a comment was the right choice.