Thankyou Andrew for working on this - it is sorely needed.
Some points I think we need voting/consensus on:
Agreed, this needs further discussion and clarification, but I feel it's one of the most important changes.
- "Contrary to the standard Moodle coding style,
- "You are going to have to work very hard to convince me this is a good idea. We use serveral third-party camelcase libraries in PHP too, and the world has not ended." Thanks Tim. Yes, we may use lots of libraries in PHP which follow this guidance, but most of those libraries are fairly abstracted away and we rarely deal with them. Conversely, with YUI, every time you wish to change a setting for anything that YUI handles, you must use camelCase. With the nature of JS, we frequently have Moodle code sat right next to code changing YUI objects. If you use a Moodle dialogue, you're really using a YUI Panel + YUI Widget + Moodle magic. You're proposing making it such that developers have to use a combination of camelCase and moodlecase in code which sits side-by-side to modify the same object. Also, it's not just me that's wishing to use camelCase for JS. --Andrew Nicols (talk) 16:16, 16 October 2013 (WST)
"be spread across multiple lines for complex types (including all objects and arrays, no matter how simple"
I don't see this as a major sticker - since we minify all code going out now, there's no reason not to and it means that we can get the full blame history much more easily.
- Although you have this rule to make diffs better, in the Number of variable declarations section you have examples that make diffs worse. Can we make it consistent.--
- I think it is crazy to require all object literals to be spread over multiple lines. It should be on a case by case basis. We allow that in PHP. Diffs might be clearer if we put a newline after every single token, but you wouldn't want to code like that. git can do quite nice diffs within lines anyway.--Tim Hunt (talk) 16:02, 16 October 2013 (WST)
We could be more specific about which yuidoc tags are required (Where is @namespace required?)
That's a hard one - I don't think that we should duplicate the entire yuidoc syntax guide here but perhaps once we get these docs ratified and start to generate real YUIDoc, we will have more of an idea. @namespace isn't required at all, but it is useful in modules with submodules primarily.
- I agree. Just make the word YUIDoc a link to a separate page that explains (could even go to YUI's site.)--Tim Hunt (talk) 16:02, 16 October 2013 (WST)
with a maximum length of 150
Okay, that can probably be dropped... but we should make the value in our .jshintrc match the value we wish this to be (180 chars is the figure mentioned in the standard style IIRC)
"In the case of object property assignation, there should be a space after the colon, but not before."
Property assignation is not really the same as an operator so I feel that these should be separate rules. Most JSON resources out there follow this standard -- see http://www.freeformatter.com/json-formatter.html#ad-output for example. Unless we have good reason, why should we break from this? It's also the format described by the RFC: http://www.ietf.org/rfc/rfc4627.txt (Section 8). Additionally, when writing in natural language, you don't write:
E-mail : email@example.com
You write it as:
- What you propose is correct. Interstingly, some languages (e.g. French I think) do put a space before colons, so this is a cultural thing, but Moodle code is English.--Tim Hunt (talk) 16:02, 16 October 2013 (WST)
Some instructions on how to use YUIdoc / shifter to check the format of the JS/comments would be welcomed.
There is already documentation on how to use Shifter, and YUIDoc. We could admittedly do with more. If others wish to contribute, I'd very happy to have help there ;)