From bd05c0f25e1285e46bbbc181f4e9b1b50bad3e47 Mon Sep 17 00:00:00 2001 From: sihao Date: Wed, 23 Dec 2015 03:57:57 +0800 Subject: [PATCH 1/3] Fixes #91 Based on the C++ coding standards md from #93 --- contents/coding-standards-javascript.md | 155 ++++++++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 contents/coding-standards-javascript.md diff --git a/contents/coding-standards-javascript.md b/contents/coding-standards-javascript.md new file mode 100644 index 0000000..c4be443 --- /dev/null +++ b/contents/coding-standards-javascript.md @@ -0,0 +1,155 @@ +# Javascript Style Guide + +## Table of Contents +- [Specific Rules](#specific-rules) +- [General Rules](#general-rules) +- [Additional Reading](#additional-reading) + +## Specific Rules +1. Line break limit at 110 char, not 80 char +2. 4 spaces indentation, not 2 spaces, not tabs +3. Constants named in screaming snake case + + ```javascript + // bad + var feedbackresponserecipient = 'responserecipient'; + + // badAsWell + var feedbackResponseRecipient = 'responserecipient'; + + // b_a_d + var feedback_response_recipient = 'responserecipient'; + + // G_O_O_D + var FEEDBACK_RESPONSE_RECIPIENT = 'responserecipient'; + ``` + +4. Line wrapping rules for improving readability [follow TEAMMATES Java Style Guide files rule 3](https://docs.google.com/document/pub?id=1iAESIXM0zSxEa5OY7dFURam_SgLiSMhPQtU0drQagrs&embedded=true): + + When wrapping lines, the main objective is to improve readability. Feel free to break rules if it improves readability. Do not accept the auto-formatting suggested by the IDE as Eclipse’s JavaScript auto-formatting is very different from that suggested by TEAMMATES. + + It is OK to exceed the limit slightly or wrap the lines much shorter than limit. + + In general, + - Break after a comma. + + ```javascript + // Bad + var alphabets = [ + a + , b + , c + ]; + + // Good + var alphabets = [ + a, + b, + c + ]; + + // Bad + var numbers = { + one: 1 + , two: 2 + , three: 3 + , four: 4 + }; + + // Good + var numbers = { + one: 1, + two: 2, + three: 3, + four: 4 + }; + ``` + - Align the new line with the beginning of the parent element. + + ```javascript + // Bad + myFunction(arg1, arg2, arg3, + nonAlignedArg4, arg5); + + // Good + myFunction(arg1, arg2 + arg3, arg4); + myFunction(arg1, + myOtherFunction(arg2, + arg3), + arg4); + ``` + + - Break before an operator. This also applies to other "operator-like" symbols like the dot separator (.). + + ```javascript + // Bad + mySum = a + b + c + + d; + myString = ‘Long line split’ + + ‘split into two parts’; + $('#responses'). + find('.selected'). + highlight(). + end(). + find('.open'). + updateCount(); + + // Good + mySum = a + b + c + + d; + myString = ‘Long line split’ + + ‘split into two parts’; + $('#responses') + .find('.selected') + .highlight() + .end() + .find('.open') + .updateCount(); + ``` + + - Prefer higher-level breaks to lower-level breaks. In the example below, the first is preferred, since the break occurs outside the parenthesized expression, which is at a higher level. + + ```javascript + // Bad + longName1 = longName2 * (longName3 + longName4 + - longName5) + 4 * longName6; + + // Good + longName1 = longName2 * (longName3 + longName4 - longName5) + + 4 * longName6; + ``` + + - Here are three acceptable ways to format ternary expressions: + + ```javascript + // Bad + alpha = (aLongBooleanExpression) ? beta + : gamma; + alpha = (aLongBooleanExpression) ? beta + : gamma; + alpha = (aLongBooleanExpression) + ? beta + : gamma; + + // Good + alpha = (aLongBooleanExpression) ? beta : gamma; + alpha = (aLongBooleanExpression) ? beta + : gamma; + alpha = (aLongBooleanExpression) + ? beta + : gamma; + ``` + +Main rule of the thumb: To be consistent with Java coding style in TEAMMATES + +## General Rules +- Refer to [airbnb Javascript Style Guide](https://github.com/airbnb/javascript/tree/master/es5) + +## Additional Reading +1. [Javascript Scoping and Hoisting](http://www.adequatelygood.com/JavaScript-Scoping-and-Hoisting.html) +2. [Truth Equality and Javascript](https://javascriptweblog.wordpress.com/2011/02/07/truth-equality-and-javascript/#more-2108) +3. [Future of Javascript (ES6 - Incoming Features)](https://github.com/lukehoban/es6features) +4. [ES6 Compatibility in Browsers](http://kangax.github.io/compat-table/es6/) +5. [Useful CSS Selectors to know](http://code.tutsplus.com/tutorials/the-30-css-selectors-you-must-memorize--net-16048) +6. [W3schools CSS Selectors Reference](http://www.w3schools.com/cssref/css_selectors.asp) \ No newline at end of file From fb28c3689c4683d467446ef47c74b3ab157b5d04 Mon Sep 17 00:00:00 2001 From: sihao Date: Tue, 5 Jan 2016 04:38:04 +0800 Subject: [PATCH 2/3] 1. Updated format to adhere to example #97 2. Modified the content based on comments given. 3. Included html file to reference to markdown file --- contents/coding-standards-javascript.html | 26 ++++++++++ contents/coding-standards-javascript.md | 59 +++++++++++++---------- 2 files changed, 60 insertions(+), 25 deletions(-) create mode 100644 contents/coding-standards-javascript.html diff --git a/contents/coding-standards-javascript.html b/contents/coding-standards-javascript.html new file mode 100644 index 0000000..397d2b6 --- /dev/null +++ b/contents/coding-standards-javascript.html @@ -0,0 +1,26 @@ + + + + + + + + Javascript Style Guide + + + + + + + diff --git a/contents/coding-standards-javascript.md b/contents/coding-standards-javascript.md index c4be443..2d26ce6 100644 --- a/contents/coding-standards-javascript.md +++ b/contents/coding-standards-javascript.md @@ -1,33 +1,42 @@ # Javascript Style Guide - -## Table of Contents -- [Specific Rules](#specific-rules) -- [General Rules](#general-rules) -- [Additional Reading](#additional-reading) - -## Specific Rules -1. Line break limit at 110 char, not 80 char -2. 4 spaces indentation, not 2 spaces, not tabs -3. Constants named in screaming snake case + + - Specific Rules + - General Rules + - Additional Reading + + ## Specific Rules + - __Line Break Limit__ + + Limits are at 110 characters instead of 80 characters + + - __Indentation__ + + Indentation should be 4 spaces for javascript files. + 4 spaces should be used instead of 2 `spaces` or `tab`. + + - __Constants__ + + Constant should use screaming snake case ```javascript // bad - var feedbackresponserecipient = 'responserecipient'; + var foobardescription = 'helloworld'; // badAsWell - var feedbackResponseRecipient = 'responserecipient'; + var fooBarDescription = 'helloworld'; // b_a_d - var feedback_response_recipient = 'responserecipient'; + var foo_bar_description = 'helloworld'; // G_O_O_D - var FEEDBACK_RESPONSE_RECIPIENT = 'responserecipient'; + var FOO_BAR_DESCRIPTION = 'helloworld'; ``` + + - __Line wrapping rules__ + + Line wrapping rules for improving readability [follow Java Style Guide files rule 3] -4. Line wrapping rules for improving readability [follow TEAMMATES Java Style Guide files rule 3](https://docs.google.com/document/pub?id=1iAESIXM0zSxEa5OY7dFURam_SgLiSMhPQtU0drQagrs&embedded=true): - - When wrapping lines, the main objective is to improve readability. Feel free to break rules if it improves readability. Do not accept the auto-formatting suggested by the IDE as Eclipse’s JavaScript auto-formatting is very different from that suggested by TEAMMATES. - + When wrapping lines, the main objective is to improve readability. Feel free to break rules if it improves readability. It is OK to exceed the limit slightly or wrap the lines much shorter than limit. In general, @@ -86,8 +95,8 @@ // Bad mySum = a + b + c + d; - myString = ‘Long line split’ + - ‘split into two parts’; + myString = 'Long line split' + + 'split into two parts'; $('#responses'). find('.selected'). highlight(). @@ -98,8 +107,8 @@ // Good mySum = a + b + c + d; - myString = ‘Long line split’ - + ‘split into two parts’; + myString = 'Long line split' + + 'split into two parts'; $('#responses') .find('.selected') .highlight() @@ -141,12 +150,12 @@ : gamma; ``` -Main rule of the thumb: To be consistent with Java coding style in TEAMMATES + Main rule of the thumb: To be consistent with Java coding style -## General Rules + ## General Rules - Refer to [airbnb Javascript Style Guide](https://github.com/airbnb/javascript/tree/master/es5) -## Additional Reading + ## Additional Reading 1. [Javascript Scoping and Hoisting](http://www.adequatelygood.com/JavaScript-Scoping-and-Hoisting.html) 2. [Truth Equality and Javascript](https://javascriptweblog.wordpress.com/2011/02/07/truth-equality-and-javascript/#more-2108) 3. [Future of Javascript (ES6 - Incoming Features)](https://github.com/lukehoban/es6features) From 1448e857357199c3cc070891fd29db1f3a597120 Mon Sep 17 00:00:00 2001 From: sihao Date: Tue, 5 Jan 2016 09:06:22 +0800 Subject: [PATCH 3/3] Made changes according to comments 1. Remove wrap from spaces as code 2. Updated link 3. Updated the presentation of examples 4. Updated link on README.md --- README.md | 2 +- contents/coding-standards-javascript.md | 313 ++++++++++++++++-------- 2 files changed, 212 insertions(+), 103 deletions(-) diff --git a/README.md b/README.md index 8b33d62..f18f627 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ If you would like to contribute code, here is the procedure: * Minimize inline styles. * When in doubt, you can refer to these style guides from the TEAMMATES project: - [JavaScript](https://docs.google.com/document/d/1gZ6WG6HBTJYHAtVkz9kzi_SUuzfXqzO-SvFnLuag2xM/pub?embedded=true), + [JavaScript](https://cdn.rawgit.com/nus-cs2103/website/master/contents/coding-standards-javascript.html), [CSS](https://docs.google.com/document/d/1wA9paRA9cS7ByStGbhRRUZLEzEzimrNQjIDPVqy1ScI/pub), [HTML](https://docs.google.com/document/d/12PJYbQoqjK-0LzaUuguQ4kGE--eikCcHfwzZDGwFOJ0/pub?embedded=true) 6. Test the code in your computer.
diff --git a/contents/coding-standards-javascript.md b/contents/coding-standards-javascript.md index 2d26ce6..fed09b6 100644 --- a/contents/coding-standards-javascript.md +++ b/contents/coding-standards-javascript.md @@ -12,143 +12,254 @@ - __Indentation__ Indentation should be 4 spaces for javascript files. - 4 spaces should be used instead of 2 `spaces` or `tab`. + 4 spaces should be used instead of 2 spaces or `tab`. - __Constants__ Constant should use screaming snake case - - ```javascript - // bad - var foobardescription = 'helloworld'; - - // badAsWell - var fooBarDescription = 'helloworld'; - - // b_a_d - var foo_bar_description = 'helloworld'; - - // G_O_O_D - var FOO_BAR_DESCRIPTION = 'helloworld'; - ``` + + + + + + + + + + + + + + + + + + + + + + +
GoodBad
+ 
+   // G_O_O_D
+   var FOO_BAR_DESCRIPTION = 'helloworld';
+
+ 		+ 
+   // bad
+   var foobardescription = 'helloworld';
+
+
+ + 
+   // badAsWell
+   var fooBarDescription = 'helloworld';
+
+
+ + 
+   // b_a_d
+   var foo_bar_description = 'helloworld';
+
+
+ + 
+   // bad
+   var foobardescription = 'helloworld';
+
+
- __Line wrapping rules__ - Line wrapping rules for improving readability [follow Java Style Guide files rule 3] + Line wrapping rules for improving readability [follow Java Style Guide files rule 3] When wrapping lines, the main objective is to improve readability. Feel free to break rules if it improves readability. It is OK to exceed the limit slightly or wrap the lines much shorter than limit. In general, - Break after a comma. - - ```javascript - // Bad + + + + + + + + + + + + + + +
GoodBad
+ 
+   // Good
    var alphabets = [
-           a
-       ,   b
-       ,   c
+           a,
+           b,
+           c
    ];
-
-   // Good
+
+ 		+ 
+   // Bad
    var alphabets = [
-       a,
-       b,
-       c
+               a
+           ,   b
+           ,   c
    ];
-
+
+
+ 
+  // Good
+  var numbers = {
+         one: 1,
+         two: 2,
+         three: 3,
+         four: 4
+   };	
+
+ 		+ 
    // Bad
    var numbers = {
-           one: 1
-       ,   two: 2
-       ,   three: 3
-       ,   four: 4
-   };
-
-   // Good
-   var numbers = {
-      one: 1,
-      two: 2,
-      three: 3,
-      four: 4
+               one: 1
+           ,   two: 2
+           ,   three: 3
+           ,   four: 4
    };
-  ```
+
+
+ - Align the new line with the beginning of the parent element. - - ```javascript - // Bad - myFunction(arg1, arg2, arg3, - nonAlignedArg4, arg5); - + + + + + + + + + + +
GoodBad
+ 
    // Good
    myFunction(arg1, arg2
-              arg3, arg4);
-   myFunction(arg1,
-             myOtherFunction(arg2,
-                             arg3),
-             arg4);
-  ```
+                   arg3, arg4);
+       myFunction(arg1,
+                   myOtherFunction(arg2,
+                                  arg3),
+                   arg4);
+
+ 		+ 
+   // Bad
+   myFunction(arg1, arg2, arg3,
+          nonAlignedArg4, arg5);
+
+
- Break before an operator. This also applies to other "operator-like" symbols like the dot separator (.). - ```javascript - // Bad - mySum = a + b + c + - d; - myString = 'Long line split' + - 'split into two parts'; - $('#responses'). - find('.selected'). - highlight(). - end(). - find('.open'). - updateCount(); - + + + + + + + + + +
GoodBad
+ 
   // Good
-  mySum = a + b + c
-          + d;
+  mySum = a  b  c
+               d;
   myString = 'Long line split'
-             + 'split into two parts';
+                  'split into two parts';
   $('#responses')
-     .find('.selected')
-         .highlight()
-         .end()
-     .find('.open')
-         .updateCount();
-  ```
+         .find('.selected')
+             .highlight()
+             .end()
+        .find('.open')
+             .updateCount();
+
+ 		+ 
+   // Bad
+  mySum = a  b  c 
+               d;
+  myString = 'Long line split' 
+                 'split into two parts';
+  $('#responses').
+         find('.selected').
+             highlight().
+             end().
+         find('.open').
+             updateCount();
+
+
- Prefer higher-level breaks to lower-level breaks. In the example below, the first is preferred, since the break occurs outside the parenthesized expression, which is at a higher level. - ```javascript - // Bad - longName1 = longName2 * (longName3 + longName4 - - longName5) + 4 * longName6; - - // Good - longName1 = longName2 * (longName3 + longName4 - longName5) - + 4 * longName6; - ``` - + + + + + + + + + +
GoodBad
+ 
+   // Good
+  longName1 = longName2 * (longName3  longName4 - longName5)
+                   4 * longName6;
+
+ 		+ 
+   // Bad
+  longName1 = longName2 * (longName3  longName4
+                  - longName5)  4 * longName6;
+
+
+ - Here are three acceptable ways to format ternary expressions: - ```javascript - // Bad - alpha = (aLongBooleanExpression) ? beta - : gamma; + + + + + + + + + +
GoodBad
+ 
+   // Good
+  alpha = (aLongBooleanExpression) ? beta : gamma;
   alpha = (aLongBooleanExpression) ? beta
-           : gamma;
-  alpha = (aLongBooleanExpression)
-                              ? beta
                                        : gamma;
-
-  // Good
-  alpha = (aLongBooleanExpression) ? beta : gamma;
+  alpha = (aLongBooleanExpression)
+            ? beta
+            : gamma;
+
+ 		+ 
+   // Bad
+  alpha = (aLongBooleanExpression) ? beta
+            : gamma;
   alpha = (aLongBooleanExpression) ? beta
-                                   : gamma;
+               : gamma;
   alpha = (aLongBooleanExpression)
-        ? beta
-        : gamma;
-  ```
+                                  ? beta
+                                           : gamma;
+
+
Main rule of the thumb: To be consistent with Java coding style @@ -159,6 +270,4 @@ 1. [Javascript Scoping and Hoisting](http://www.adequatelygood.com/JavaScript-Scoping-and-Hoisting.html) 2. [Truth Equality and Javascript](https://javascriptweblog.wordpress.com/2011/02/07/truth-equality-and-javascript/#more-2108) 3. [Future of Javascript (ES6 - Incoming Features)](https://github.com/lukehoban/es6features) -4. [ES6 Compatibility in Browsers](http://kangax.github.io/compat-table/es6/) -5. [Useful CSS Selectors to know](http://code.tutsplus.com/tutorials/the-30-css-selectors-you-must-memorize--net-16048) -6. [W3schools CSS Selectors Reference](http://www.w3schools.com/cssref/css_selectors.asp) \ No newline at end of file +4. [ES6 Compatibility in Browsers](http://kangax.github.io/compat-table/es6/) \ No newline at end of file