Hi, The patch looks good. I commented on it but it should not be much trouble to clarify / fix the issue.
>>> Language Files Code Comment Comment % Blank >>> Total >>> ---------------- ----- --------- --------- --------- --------- >>> --------- >>> javascript 1 774 37 4.6% 68 >>> 879 >>> ---------------- ----- --------- --------- --------- --------- >>> --------- >>> Total 1 774 37 4.6% 68 >>> 879 >>> >>> The quality of those comments is also such that they are written more as >>> small reminders to the original coder than they are as robust hints for >>> someone new to the code. >>> >>> This makes it quite difficult for someone new to the code like myself to >>> jump in and understand what is going on where. What would be immensely >>> helpful for someone just joining like me is if each method (or "switch") >>> could have a small comment saying what it's for, what it's context is, what >>> goes in and what is expected to come out. As it was I eventually worked it >>> out, I think, but it was more difficult than it needed to be. >>> I apologize for the inconvenience. I gave up writing comments a long time ago and I'm not sure I will be able to go back. The primary reason is that I got used to read tests as I would read comments. You may have found that each function in jquery.cardstories.js has it's counterpart in the test.js (one test or sometime more if the complexity of the function requires it). When I try to figure out what a function does, I read the corresponding test(s). I realize this is not a typical habit and it should be made clear from the start. I am willing to write documentation and I spent a few hours documenting the plugin API this sunday, so that plugin writers do not need to read the internals ( and therefore the tests ... ;-) to figure out what is available. I should also write a one or two page architecture summary that explains how each element relate to the other ( the client to the server, the plugin to the core, the auth plugin to the solo plugin etc.). Cheers
<<attachment: loic.vcf>>
signature.asc
Description: OpenPGP digital signature
_______________________________________________ Farsides mailing list - [email protected] Wiki: http://farsides.com/ List: http://farsides.com/ml/ Forum: http://farsides.com/forum/ Ideas: http://farsides.com/ideas/ Chat: http://farsides.com/chat/
