Publish and adhere to modern JavaScript coding standards (wiki)

[GoogleCodeExporter]

When a project lacks coding standards, one of two things will happen: either 
the code will become less readable over time, or else 
the task of changing contributed code to meet a single standard will fall on 
the project owners, rather than the contributors.  (The 
point of open source is to distribute the work, not to centralize it.)

I would like to see a coding standards section added to the wiki.  The 
standards should be created with the top priorities being 
readability, clarity of intention, and prevention of coding errors.  There are 
no prizes for compact code.  There is a minimized 
version for deployment, so compactness of code is not a consideration. 

In addition, I propose the following standards as a starting point:

1. K&R coding style, where the opening brace is placed on the same line as the 
keyword.  For example:

    if (condition) {
        // do something
    }

2. Curly braces used in *every* control control structure, even when not 
necessary.  This greatly enhances readability and clarity of 
intended purpose, and reduces coding errors.

3. Parentheses around *every* condition, which reduces coding errors and helps 
readability immensely.  For example:

    NO:  if (top > 0 && isLarge && bottom < 100) {...

    YES:  if ((top > 0) && (isLarge) && (bottom < 100)) {...

4. Strings delimited with full quotes ("...").

5. Variable, function, and method names in camelCase.  Class names requiring 
the use of the word "new" should be ProperCase. 

6. All comments should be of the single-line variety ("//").

7. All statements, assignment, and function declaration must end with a 
semicolon.  This *includes* statements just before a 
closing curly brace and globally-scoped function declarations.  The only 
structures that should not be terminated with a semicolon 
are if, while, do, for, switch, and try.  

8. with and eval should never be used.

9. Always use parentheses with typeof.  For example, typeof(myVar).  Also, 
parentheses should always be used when math 
operators are directly next to each other.  NO: x = y + ++z;  YES: x = y + 
(++z);

10. When a line is continued on the next line, it should always end with an 
operator.  For example:

    NO:
    var myString = "This is"    // End of statement or continued?
        + " my string.";

    YES:
    var myString = "This is" +    // Clearly will be continued
        " my string.";

11. Spaces:
    a. Always one space after the word "function".  NO: var a = function() {...  YES: var a = function () {....
    b. One space before and after an operator (except ++ and --).  NO: var a=(b+c-1);  YES: var a = (b + c - 1);
    c. No space immediately after a left paren or immediately before a right paren.  NO: ( a + 1 )  YES: (a + 1)
    d. Always one space after return.  NO: return(a);  YES: return (a);
    e. One space after each comma (anywhere commas are used), as well as after semicolons within the parentheses of a for 
statement.

12. Line breaks:
    a. The following structures should be preceded by one blank line: if, while, do, for, switch, try, and function.
    b. When ending multiple structures (such as an "if" at the end of a "while" loop), each ending curly brace should be on its own 
line, with no line breaks between them.  For example:
        while (x < 10) {
            ...
            if (exit) {
                break;
            }
        }        // No line break between end braces

13. The exact equality/inequality operators (===/!==) should be used whenever 
possible, *especially* when testing for 
false/undefined/null/zero values and with typeof.  NO: (typeof(val) == 
"undefined")  YES: (typeof(val) === "undefined")

Original issue reported on code.google.com by t...@speednet.biz on 26 Jul 2008 at 7:45

[GoogleCodeExporter]

I would also like to request that the spaces (current SVN is based on 4 space 
tabs) 
be changed to actual tabs so the user can define the tab spacing to whatever 
they 
find best.

Original comment by tsimm...@gmail.com on 15 Aug 2008 at 7:19

[GoogleCodeExporter]

Great standards Todd! I think standards like this are essential when multiple 
people
are working on a single project.

Original comment by tgo...@gmail.com on 18 Nov 2008 at 4:02

[GoogleCodeExporter]

Maybe there should be some standards for the CSS as well? It's pretty clean how 
it
is, but just for the sake of standardizing it.

Original comment by tgo...@gmail.com on 18 Nov 2008 at 4:02

[GoogleCodeExporter]

It's worth running the code through JSLint - www.jslint.com - if it hasn't 
already,
as this will catch common problems, especially once you start minifying the 
code for
 production use.

Original comment by tim.bea...@gmail.com on 19 Nov 2008 at 3:35

[GoogleCodeExporter]

@Tim:  That's possible, but I'm not sure the default code checks with JSLint 
would 
be the best solution for iUI.  Unless all of the default options were to be 
selected, it would still require that the group come up with the proper options 
to 
apply to JSLint -- and that requires setting the actual standards first.

I don't disagree that using the tool is a good idea.  In fact, it would be a 
great 
way to validate the library prior to new release.

@tgolen: I agree, it would makes sense to standardize the CSS as well, although 
that 
will certainly be easier than the JS!  It would be nice to also provide a 
minified 
version of the CSS file, in addition to the current minified JS file.  If you 
haven't experienced minified CSS, I host a CSS minifier here which can do it 
for you 
on the fly: http://www.lotterypost.com/css-compress.aspx

BTW, it's been several months since I wrote the above standards, and since that 
time 
I have come into some information that would cause me to slightly alter them.

In #7 I would *remove* the statement about ending globally-scoped function 
declarations with a semi-colon.  I would change the final sentence to "The only 
structures that should not be terminated with a semicolon are do, for, 
function, 
if/else, switch, try/catch/finally, and while."  Doug Crockford has confirmed 
that 
it is not proper syntax to end a "stand-alone" function definition with a 
semi-colon.

I agree with comment #1 from tsimmons about using tabs instead of spaces for 
all 
indentation.  In addition to providing more flexibility to the developer, it 
shrinks 
the size of the file and makes spacing more consistent.

We also need comment standards in the code.  I would really like to get the 
methods 
and properties documented within the file itself.

Comments are definitely one area where everyone has their own likes and 
dislikes, so 
I'll just put my opinion out there for public consumption.

I like the standard JavaScript comment format that Microsoft has come up with, 
because it is:

- highly readable
- formatted as embedded XML so automated apps can read the comments and 
generate 
great stand-alone documentation (several utilities do this already)
- provides automatic IntelliSense in VS 2005/2008
- provides a standard way to document objects like DOM elements and Arrays, 
which 
normally are difficult because of the way they are not distinct within the 
language

jQuery has documented their entire core library with Microsoft-style comments, 
so it 
is not uncommon for non-MS projects.  

Here's a link to the JS doc standards: 
http://weblogs.asp.net/bleroy/archive/2007/04/23/the-format-for-javascript-doc-
comments.aspx

Original comment by t...@speednet.biz on 19 Nov 2008 at 7:26

[GoogleCodeExporter]

That's interesting about the JS doc standards. I've never used standards like 
that,
but it would only take some getting used to. Looks good to me.

Original comment by tgo...@gmail.com on 19 Nov 2008 at 11:45

[GoogleCodeExporter]

I hear you, I think it's unusual for anyone the first time they see it.  If you 
use 
VS 2005 or 2008 (or even VS express) (I think), the first time you see your 
comments 
come up as IntelliSense, you'll be a convert.  You get all the same prompting 
as you 
would normally, with the descriptions of the arguments being shown as you enter 
them, etc.  When type the the "dot" after an object you defined, you see the 
members 
of the object with the descriptions.  It's very cool.

The second big thing is when you see how you can create excellent documentation 
in a 
PDF file, help file, or web site -- generated directly from the inline 
comments.  
It's amazing stuff, and does really help with open-source projects, when many 
people 
are trying to make sense of the same thing.

Original comment by t...@speednet.biz on 20 Nov 2008 at 2:43

[GoogleCodeExporter]

Just having read through the source, I am voting this issue up. The standards
outlined here aren't exactly those I use in my own work, but they're pretty 
close,
and much closer to the recommendations of Crockford and others. Any defined 
standard
is better than no defined standard as potential contributors (like myself) will 
have
a better idea of how to conform to the existing codebase.

Original comment by segdeha on 5 Jun 2009 at 12:38

[GoogleCodeExporter]

iui.js is only 500 lines and I've been trying my best to follow the style that 
Joe Hewitt used in the original.  In the 
short run (next release or two) I'd like to stick with Joe's style.  The above 
guidelines look reasonable to me --
although I'm one of the weirdos who like opening braces and closing braces to 
align vertically.

I would very much like to get JSLint integrated into the Ant build as a first 
step.

Original comment by msgilli...@gmail.com on 5 Jun 2009 at 3:25