Talk:Javascript/Coding Style: Difference between revisions
Damyon Wiese (talk | contribs) (Created page with "Thankyou Andrew for working on this - it is sorely needed. Some points I think we need voting/consensus on: "Contrary to the standard Moodle coding style, we prefer to use c...") |
(Add replies to the areas raised) |
||
| Line 3: | Line 3: | ||
Some points I think we need voting/consensus on: | Some points I think we need voting/consensus on: | ||
" | ---- | ||
'''"Contrary to the standard Moodle coding style, we prefer to use camelCase for JavaScript."''' | |||
Agreed, this needs further discussion and clarification, but I feel it's one of the most important changes. | |||
--[[User:Andrew Nicols|Andrew Nicols]] ([[User talk:Andrew Nicols|talk]]) 14:46, 16 October 2013 (WST) | |||
Some instructions on how to use YUIdoc / shifter to check the format of the JS/comments would be welcomed. | ---- | ||
'''"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. | |||
--[[User:Andrew Nicols|Andrew Nicols]] ([[User talk:Andrew Nicols|talk]]) 14:46, 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. | |||
--[[User:Andrew Nicols|Andrew Nicols]] ([[User talk:Andrew Nicols|talk]]) 14:46, 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) | |||
--[[User:Andrew Nicols|Andrew Nicols]] ([[User talk:Andrew Nicols|talk]]) 14:46, 16 October 2013 (WST) | |||
---- | |||
'''"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: | |||
<pre>E-mail : fred@example.com</pre> | |||
You write it as: | |||
<pre>E-mail: fred@example.com</pre> | |||
--[[User:Andrew Nicols|Andrew Nicols]] ([[User talk:Andrew Nicols|talk]]) 14:46, 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 ;) | |||
--[[User:Andrew Nicols|Andrew Nicols]] ([[User talk:Andrew Nicols|talk]]) 14:46, 16 October 2013 (WST) | |||
---- | |||
Revision as of 06:46, 16 October 2013
Thankyou Andrew for working on this - it is sorely needed.
Some points I think we need voting/consensus on:
"Contrary to the standard Moodle coding style, we prefer to use camelCase for JavaScript."
Agreed, this needs further discussion and clarification, but I feel it's one of the most important changes.
--Andrew Nicols (talk) 14:46, 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.
--Andrew Nicols (talk) 14:46, 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.
--Andrew Nicols (talk) 14:46, 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)
--Andrew Nicols (talk) 14:46, 16 October 2013 (WST)
"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 : fred@example.com
You write it as:
E-mail: fred@example.com
--Andrew Nicols (talk) 14:46, 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 ;)
--Andrew Nicols (talk) 14:46, 16 October 2013 (WST)
