Converted JavascriptStyleGuide.md
diff --git a/JavascriptStyleGuide.md b/JavascriptStyleGuide.md new file mode 100644 index 0000000..f5fb2aa --- /dev/null +++ b/JavascriptStyleGuide.md
@@ -0,0 +1,90 @@ +As more Javascript code in Melange is going to be developed, here's a draft for code guidelines. These guidelines are inspired by [PythonStyleGuide](PythonStyleGuide.md) page (but adapted to JS), and from [Code conventions for the Javascript Programming Language](http://javascript.crockford.com/code.html). In this very moment our code doesn't respect them, but these are going to be strict rules when [JavascriptRefactoring](JavascriptRefactoring.md) will come to an end. More infos on _why_ these rules are important later. + +As poor-written Javascript is more dangerous than as it's in other languages, we're going to use [Jslint](http://www.jslint.com/) to verify code conventions compliance. See [JavascriptRefactoring](JavascriptRefactoring.md) for more information on how to use it. + +More infos on how to write good Javascript code on [Efficient javascript article](http://dev.opera.com/articles/view/efficient-javascript/) and in [Jslint code checking rules](http://www.jslint.com/lint.html), some [useful patterns](http://www.klauskomenda.com/code/javascript-programming-patterns/) and a great [article about closures](http://www.jibbering.com/faq/faq_notes/closures.html) + +# Javascript Language Rules +1. _Private and public/privileged vars/functions_: we're going to use [Module pattern](http://www.klauskomenda.com/code/javascript-programming-patterns/#module), more info in [JavascriptRefactoring](JavascriptRefactoring.md) page. + +2. _With statement_: Do **not** use **with** statement. If you want to provide shortcuts, just create a variable that points to the object you want to access repeatedly. See explanations on [why with statement is harmful](http://yuiblog.com/blog/2006/04/11/with-statement-considered-harmful/) + +3. _Iterations_: as we've jQuery always loaded, use [jQuery's each() function](http://docs.jquery.com/Utilities/jQuery.each) to iterate over objects/arrays. Do not use **for...in** loops, as they can lead to [potential errors](http://yuiblog.com/blog/2006/09/26/for-in-intrigue/) + +4. _Ajax calls_: **always** use `?=_"+(new Date().getTime())` when invoking an URL to avoid caching issues + +5. _Global namespace pollution_: at least **avoid** it (more infos when we come to an agreement for [JavascriptRefactoring](JavascriptRefactoring.md)) + +# Javascript Style Rules + +1. _Semicolons_: **Always**, **not** after functions as in: + +``` + +function foo() { +}; + +``` + +This is unnecessary. But **yes** when you're storing an anonymous function inside a variable like this: + +``` + +var foo = function () { +}; + +``` + +2. _Line length_: **80** columns maximum. If you need to break one line, indent it by **2** spaces + +3. _Indentation_: **2** spaces (**no tabs**) + +4. _Whitespaces_: **no** whitespaces inside parentheses, brackets or braces + +5. _HTML Django templates_: there should be **no** code in them + +6. _Comments_: use [JSDocToolkit](http://code.google.com/p/jsdoc-toolkit/) style + +7. _Functions_: **no space** between the _name of the function_ and the parenthesis + +8. _Anonymous functions_: **1 space** between the word _function_ and the parenthesis + +9. _Immediately invoked functions_: wrap them **between parenthesis**, as in: +``` +var myvar = (function () { + return true; +}()); +``` + +10. _Objects and arrays_: use ` {} ` to declare objects (not `new Object()`) and `[]` to declare arrays (not `new Array()`) + +11. _Variables_: always use **var**, otherwise the variable will pollute the global namespace + +12. _Primitive objects_: **never** extend their prototype + +13. _String concatenation_: use + +``` +var concatenated = ["string1","string2"].join(""); +``` + +instead of + +``` +var concatenated = "string1" + "string2"; +``` + +It's usually faster for browsers and more beautiful when new lines are needed because line is too long. + +If line is too long or you're going to store HTML, than indent it like this: + +``` +var foo = [ + '<div>', + ' <table>', + ' </table>', + '</div>' +].join(""); +``` + +This won't break jsLint and helps understanding indentation in the HTML code as well. \ No newline at end of file
diff --git a/JavascriptStyleGuide.wiki b/JavascriptStyleGuide.wiki deleted file mode 100644 index d6add8a..0000000 --- a/JavascriptStyleGuide.wiki +++ /dev/null
@@ -1,93 +0,0 @@ -#summary Style guide for JavaScript code contributed to Melange -#labels Importance-Deprecated,Phase-Guidelines,Contents-Draft - -As more Javascript code in Melange is going to be developed, here's a draft for code guidelines. These guidelines are inspired by [PythonStyleGuide] page (but adapted to JS), and from [http://javascript.crockford.com/code.html Code conventions for the Javascript Programming Language]. In this very moment our code doesn't respect them, but these are going to be strict rules when [JavascriptRefactoring] will come to an end. More infos on _why_ these rules are important later. - -As poor-written Javascript is more dangerous than as it's in other languages, we're going to use [http://www.jslint.com/ Jslint] to verify code conventions compliance. See [JavascriptRefactoring] for more information on how to use it. - -More infos on how to write good Javascript code on [http://dev.opera.com/articles/view/efficient-javascript/ Efficient javascript article] and in [http://www.jslint.com/lint.html Jslint code checking rules], some [http://www.klauskomenda.com/code/javascript-programming-patterns/ useful patterns] and a great [http://www.jibbering.com/faq/faq_notes/closures.html article about closures] - -= Javascript Language Rules = -1. _Private and public/privileged vars/functions_: we're going to use [http://www.klauskomenda.com/code/javascript-programming-patterns/#module Module pattern], more info in [JavascriptRefactoring] page. - -2. _With statement_: Do *not* use *with* statement. If you want to provide shortcuts, just create a variable that points to the object you want to access repeatedly. See explanations on [http://yuiblog.com/blog/2006/04/11/with-statement-considered-harmful/ why with statement is harmful] - -3. _Iterations_: as we've jQuery always loaded, use [http://docs.jquery.com/Utilities/jQuery.each jQuery's each() function] to iterate over objects/arrays. Do not use *for...in* loops, as they can lead to [http://yuiblog.com/blog/2006/09/26/for-in-intrigue/ potential errors] - -4. _Ajax calls_: *always* use {{{?=_"+(new Date().getTime())}}} when invoking an URL to avoid caching issues - -5. _Global namespace pollution_: at least *avoid* it (more infos when we come to an agreement for [JavascriptRefactoring]) - -= Javascript Style Rules = - -1. _Semicolons_: *Always*, *not* after functions as in: - -{{{ - -function foo() { -}; - -}}} - -This is unnecessary. But *yes* when you're storing an anonymous function inside a variable like this: - -{{{ - -var foo = function () { -}; - -}}} - -2. _Line length_: *80* columns maximum. If you need to break one line, indent it by *2* spaces - -3. _Indentation_: *2* spaces (*no tabs*) - -4. _Whitespaces_: *no* whitespaces inside parentheses, brackets or braces - -5. _HTML Django templates_: there should be *no* code in them - -6. _Comments_: use [http://code.google.com/p/jsdoc-toolkit/ JSDocToolkit] style - -7. _Functions_: *no space* between the _name of the function_ and the parenthesis - -8. _Anonymous functions_: *1 space* between the word _function_ and the parenthesis - -9. _Immediately invoked functions_: wrap them *between parenthesis*, as in: -{{{ -var myvar = (function () { - return true; -}()); -}}} - -10. _Objects and arrays_: use {{{ {} }}} to declare objects (not {{{new Object()}}}) and {{{[]}}} to declare arrays (not {{{new Array()}}}) - -11. _Variables_: always use *var*, otherwise the variable will pollute the global namespace - -12. _Primitive objects_: *never* extend their prototype - -13. _String concatenation_: use - -{{{ -var concatenated = ["string1","string2"].join(""); -}}} - -instead of - -{{{ -var concatenated = "string1" + "string2"; -}}} - -It's usually faster for browsers and more beautiful when new lines are needed because line is too long. - -If line is too long or you're going to store HTML, than indent it like this: - -{{{ -var foo = [ - '<div>', - ' <table>', - ' </table>', - '</div>' -].join(""); -}}} - -This won't break jsLint and helps understanding indentation in the HTML code as well. \ No newline at end of file