Noissue - Add some more JavaScript coding guidlines

pages/coding-style.html

 title=Coding Style
 
 
 <h2 id="precedence">{{s1 Precedence}}</h2>
 
 <p>{{s2 The Adblock Plus coding style is based on others. Our rules (both general and language specific) always overrule referenced style guides. The language specific sections overrule the general section.}}</p>
 
 <h2 id="consistency">{{s3 Consistency}}</h2>
 
 <p>{{s4 Consistency is most important: Be consistent within functions, files, modules and projects. Making existing code conform with this style guide is fine, but it should happen in dedicated commits, preferably for a whole module or project at once.}}</p>
 
 <h2 id="general">{{s5 General}}</h2>
 <ul>
   <li>{{s6 Follow the Mozilla Coding Style's <a href="https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style#General_C.2FC.2B.2B_Practices">general practices</a> and its <a href="https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style#Naming_and_Formatting_code">naming and formatting rules</a>.}}</li>
   <li>{{s8 All files should have a <a href="license-headers">license header</a>, but no mode line comments.}}</li>
   <li>{{s9 Newline at end of file, otherwise no trailing whitespace.}}</li>
   <li>{{s10 Lines can be longer than the limit, if limiting line length would hurt readability in a particular case.}}</li>
   <li>{{s11 Opening braces always go on their own line.}}</li>
   <li>{{s12 No hungarian notation, no special variable name prefixes or suffixes denoting type or scope. All variable names start with a lower case letter.}}</li>
   <li>{{s13 Don't comment code out, delete it.}}</li>
   <li>{{todo-comments Don't add TODO comments, create an <a href="https://issues.adblockplus.org">issue</a> and reference it in a comment instead.}}</li>
 </ul>
 
 <h2 id="javascript">{{s14 JavaScript}}</h2>
 <ul>
   <li>{{s15 Follow the Mozilla Coding Style's <a href="https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style#JavaScript_practices">JavaScript practices</a>.}}</li>
   <li>{{javascript-strict Always use <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Strict_mode">strict mode</a>.}}</li>
   <li>{{javascript-opening-braces Opening braces of object literals don't go on their own line when that would cause a syntax error.}}</li>
+  <li>{{javascript-if-else-braces When an <code><fix>if</fix></code> statement, an <code><fix>else</fix></code> statement or a loop spans over more than one line always enclose it with braces. When an <code><fix>if</fix></code> or <code><fix>else</fix></code> statement uses braces the opposing block should do too.}}</li>
   <li>{{s18 In classes, prefix private functions with a single underscore to make them pseudo-private.}}</li>
-  <li>{{javascript-if-else-braces When an <code><fix>if</fix></code> statement, an <code><fix>else</fix></code> statement or a loop spans over more than one line always enclose it with braces. When an <code><fix>if</fix></code> or <code><fix>else</fix></code> statement uses braces the opposing block should do too.}}</li>

[Sebastian Noack, 2017/01/18 09:56:20]

Perhaps we should put the two rules about braces next to each other.

[kzar, 2017/01/18 10:26:42]

Done.

-  <li>{{javascript-object-proto-null Use <code><fix>Object.create</fix></code> to create an object with a specific prototype rather than by specifying or modifying the <code><fix>__proto__</fix></code> property.}}</li>

[Sebastian Noack, 2017/01/18 09:56:20]

As it stands now, this rule is kinda redundant, as it is just a random case of
"don't use deprecated APIs". Probably we don't need an explicit rule for that.

[kzar, 2017/01/18 10:26:42]

Removed.

   <h3 id="javascript-modern">{{javascript-es6 Modern JavaScript (where supported)}}</h3>
   <ul>
     <li>{{javascript-block-scoping Always use <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/block#With_let_and_const">block-scoping</a> (<code><fix>let</fix></code> / <code><fix>const</fix></code>), except when sharing global variables between scripts cannot be avoided.}}</li>
     <li>{{javascript-const Use <code><fix>const</fix></code> for constant expressions that could as well have been inlined (e.g. static parameters, imported modules, etc.).}}</li>
     <li>{{javascript-arrow Use the <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Functions/Arrow_functions">arrow function</a> syntax when passing anonymous functions that don't require the binding of their own <code><fix>this</fix></code> or <code><fix>arguments</fix></code> variables.}}</li>
     <li>{{javascript-method Use the <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Functions/Method_definitions">method definition shorthand</a> syntax when defining methods on an object.}}</li>
-    <li>{{javascript-for-of When iterating over arrays in the canonical order use the new <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/for...of">for..of</a> syntax if the loop index isn't required. (Rather than using <code><fix>for(;;)</fix></code> or the <code><fix>forEach()</fix></code> method.)}}</li>

[Sebastian Noack, 2017/01/18 09:56:20]

Just because "for..of" is linked now, doesn't mean that it cannot use source
code formatting. Also don't forget <fix> to prevent it from being translated.

  <a href=".."><code><fix>for..of</fix></code></a>

[Sebastian Noack, 2017/01/18 09:56:20]

Is it grammatically correct to end the sentence before the conjunction (i.e.
rather)?

[kzar, 2017/01/18 10:26:42]

No idea, how about "As opposed ..."?

[kzar, 2017/01/18 10:26:42]

Done.

-    <li>{{javascript-map-set Use the <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Map">Map</a> or <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Set">Set</a> data types rather than misusing plain objects.}}</li>

[Sebastian Noack, 2017/01/18 09:56:20]

I still think think talking about datatypes is inaccurate:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Data_...

Also you no longer clarify what is considered misusing plain objects. I think
the following would be more accurrate:

  Use the Map or Set objects, rather than misusing plain objects,
  when you need a hash table.

[kzar, 2017/01/18 10:26:42]

Done.

+    <li>{{javascript-for-of When iterating over arrays in the canonical order use the new <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/for...of"><code><fix>for..of</fix></code></a> syntax if the loop index isn't required. (Rather than using <code><fix>for(;;)</fix></code> or the <code><fix>forEach()</fix></code> method.)}}</li>

[saroyanm, 2017/01/18 11:27:02]

Detail: Please add full stop in the end of the line for consistency with other
list items.

[Sebastian Noack, 2017/01/18 11:38:08]

Well, if you put the whole sentence into parentheses the full-stop belongs
inside the parentheses as well. Alternatively, we could not end the sentence
there (as I suggested before):

 ... isn't required (rather than using `for(;;)` or the `forEach` method).

Or not even use parentheses:

 ... isn't required, rather than using `for(;;)` or the `forEach` method.

Or we leave it as it is. No strong opinion.

[saroyanm, 2017/01/18 11:49:49]

Learned something today. Fare enough.
No strong opinion either. LGTM still from my side.

+    <li>{{javascript-map-set Use the <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Map"><code><fix>Map</fix></code></a> or <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Set"><code><fix>Set</fix></code></a> objects, rather than misusing plain objects, when you need a hash table.}}</li>
   </ul>
 </ul>
 
 <h2 id="html-css">{{html-css HTML and CSS}}</h2>
 <ul>
   <li>{{html-css-general Follow the <a href="https://google.github.io/styleguide/htmlcssguide.xml">Google HTML/CSS Style Guide</a>.}}</li>
   <li>{{html-css-quotation Use double over single quotation marks.}}</li>
   <li>{{html-css-optional-tag Don't omit optional HTML tags.}}</li>
   <li>{{html-css-hexadecimal CSS color values should be specified in hexadecimal where possible.}}</li>
   <li>{{html-css-shorthand CSS shorthand properties usage is optional.}}</li>
@@ skipping 36 matching lines @@
 <ul>
   <li>{{objc-conventions Follow Apple's <a href="https://developer.apple.com/library/ios/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Conventions/Conventions.html">conventions</a>}}.</li>
 </ul>
 
 <h2 id="puppet">{{s31 Puppet}}</h2>
 <ul>
   <li>{{s32 Follow the <a href="http://docs.puppetlabs.com/guides/style_guide.html">Puppet Style Guide</a>.}}</li>
   <li>{{s33 Opening braces don't go on their own line.}}</li>
   <li>{{s34 Arrows should not be aligned.}}</li>
 </ul>