JavaScript / JScript Coding Standard

JavaScript Coding Standard

JavaScript is a simple Object Functional Programming Language. It was origionally designed as a Scripting Language for web developement with many of the idioms of the Self Language and the syntax of the Cee Language. TODO: What is this family of syntaxes called? Replace here. This coding standard covers the latest standard called ECMAScript 3 that features among others:

DynamicTyping

Everything is a Dictionary Data Structure (even Objects)

FirstClass functions

LexicalClosures

PrototypeBasedProgramming support

Some limited ArrayOrientedLanguage support

Although these features makes JavaScript very flexible and easy to learn, programmers inexperienced with these paradigms may have difficulty adapting. It is not the JavaLanguage; although, they share some concepts (due to an early partnership between Sun and Netscape). Nor is it the LispLanguage despite many other simularities between their individual language philosophies. JavaScript also isn't a perfect language and several JavaScriptFlaws make complex designs difficult.

Therefore developing and complying with good coding standards makes coding in JavaScript easier, faster, and more fun.

1. We should adopt class based approach rather than function based approach. This would make our code more flexible and make it easier to apply JavaScriptPatterns.Bad idea, it goes against the grain and power of the language. JavaScript is a prototyped languages that supports FirstClassFunctions and LexicalClosures, this is superior to the class based approach and far more dynamic and expressive. JavaScript is not Java.

While I tend to agree with this, I think a functional approach in JavaScript can work pretty well... Also, generic algorithms may be very powerful... -- DavidDeLis

FirstClassFunctions and LexicalClosures are orthorgonal to class-based design, and they may be used together with the traditional object-oriented approach. At least, I don't see them as direct competitors. -- JimmyCerra

Also I've discovered, to my dismay, that InternetExplorer doesn't allow you to add methods to its core DOM classes - which pretty much kills the idea of using the receiver paradigm (i.e. class-based approach). See http://www.codingforums.com/showthread.php?threadid=2948 -- RandyStafford

Wouldn't a DecoratorPattern work for this? Seems like it's a common approach to such situations. -- TomStambaugh

I wish I could use the DecoratorPattern, Tom. The problem is the web browser won't instantiate my decorators when loading a page. Instead it will instantiate its own core DOM classes - which precludes code like "document.someForm.someFunctionOfMine()". I gave up and reverted to a procedural approach, passing would-be receivers as the first arguments to functions declared on the global object. -- RandyStafford

(I may be late to the conversation.) RandyStafford, why can't you still use a decorator: "f = new Decorator(document.someForm); f.someFunctionOfMine();"? -- Jimmy Cerra

2. A JavaScript file should be considered as equivalent to a package in Java. i.e., all the related classes should be in one file. It's not pragmatic to have a file for each class as in Java. And name of the file should reflect it purpose. In the same way a package is named in Java. If the file is too big, then it's better to divide the file further.

3. Each JS file should have a header comment such as this:

  /*-------------------------------------------------------------------------

   * Gui framework classes for the Web Client are stored in this file.

   *

   * DEPENDENCIES

   * - Data.js

   * - Utils.js

   *-------------------------------------------------------------------------/

The first line gives a brief description of the file's contents and the DEPENDENCIES give the files that should be imported while using these classes. Why explicitly list dependencies? Don't JavaScriptIde's provide this kind of support?

I'll add: why hinting the dependencies? The explicit list of load()s, import()s or include()s should be explicit enough... -- DavidDeLis

For library-type files, I'm all for listing the dependencies: it has to be documented somehow, and trying to import the files without the luxury of an import statement requires assumptions about the host - it may not even be possible with some hosts. -- DanielBrockman

Don't JavaScriptIde's provide this kind of support?

What "JavaScriptIde's"? Are there any? Are any of them any good? -- TomStambaugh

4. It's better if we have no stray functions and variables. i.e., all the methods that are declared should be declared inside a class. This will solve the namespace problem and also force the developer to code in more object oriented way. While this addresses the namespace problem, generic algorithms shouldn't belong in a class... -- d

5. Use PrivateVariablesInJavaScript .

6. All variable declarations should be done with the "var" keyword and not just by assigning a value. This is actually a very good idea. It clearly differentiate between the declaration of a variable (and maybe its first assignment) and any later assignments... -- DavidDeLis Variables not declared with the "var" keyword become properties of the Global object (usually "window" or "self" in web browsers). -- Jimmy Cerra

7. All classes and methods should have comment headers similar to Java programming language. For e.g.,

  /**

   * Utility method for getting product.

   *

   * @param int a A value.

   * @param int b Another value.

   */

  function Utils_product(a, b) {

    return a*b;

  }

Here, you have noticed that both the parameters have type associated with it. The following point elaborates on it. Good idea if we find a tool similar to javadoc. Also, the type information may be irrelevant for our function... -- DavidDeLis

I like do the same thing, but in comments:

  function Utils_product( /*int*/ a, /*int*/ b ) {

It looks a little more like Java code this way, and brings the type closer to the variable. -- DanielCohen? JavaScriptIsNotJava?

8. Since JavaScript does not have any proper type concept, it's better we show the type in the method headers. This would make it clear for the reader which types the method is going to deal in. All primary types should be named after primary types of Java programming language. For types such as HTML form elements, the convention is to attach HTML before the name of the element. For e.g., HTMLForm, HTMLListBox, HTMLTextField etc. I'd disagree. Every object is a class in itself (or if you play with the prototype property, we can have real classes) and therefore a type in JavaScript. Also, many functions are type independent and there's a lot of flexibility around. Documenting a function is a good idea, but we shouldn't leave the realm of the language space... -- DavidDeLis In all my years of JavaScript programming, I never once had problems with variable casts (in fact, I rarely had those problems in strongly typed languages as well). I recommend including type information only where necessary, e.g. "var elementAsString = foo(anElement);". This way, I can concentrate on the purpose of a variable rather than its content. -- Jimmy Cerra'

JavaScript does have types, they are just dynamic, this is far more flexible than static types as all calls are polymorphic.

9. It's better to have semi-colons in the end of each statement although it's not required. It increases code reliability. Definitely agreed. One should always use semicolons both as a discipline exercise and as personal consistency in their coding. Also as JavaScript looks like CeeLanguage, semicolons are definitely more "idiomatic"... -- d Not to mention the kind of subtle bugs that automatic semicolon insertion can conjure up. -- DanielBrockman

10. In case inner classes are required in JavaScript, the naming convention should ve ParentClass?$InnerClass. This will tell the developer that this is an inner class. I'm not sure that I understand the need or purpose of this recommendation. Inner classes are inside the classes they are defined. On the other hand they are just inner functions, so the <ClassName>_<functionName> just looks good enough for this... -- DavidDeLis

11. In case we are writing browser specific code, then we should have it specified in the internal name of the method (Not the name declared in the signature of the class). i.e., <ClassName>_<methodName>_IE or <ClassName>_<methodName>_NS.

This is a bad idea and completely defeats the purpose of OO and show's a huge misunderstanding of what OO is really about. Just have two different classes, one to implement IE, one to implement Netscape, both with the same interface and dynamically switch them at runtime. Want to add Opera later, just write another.

[I agree it is a bad idea. A better idea is to use a StrategyPattern together with lambda functions. e.g.]

  var fn = isIE() ? function() {

    // IE stuff

  } : isMoz() ? function() {

    // IE stuff

  } : isOpera() ? function() {

    // Opera stuff

  } : function() {

    // Default stuff

  };

This is still a bad idea, and it still misses the entire point of OO. OO exists so that you don't have to do the switching, let the language do it for you and take advantage of polymorphism. The above code show's a complete lack of understanding of polymorphism and how it should be used. Have an opera class, an IE class, a Mozilla class, all sharing the same interface, and decide once at startup which browser you're using, and just use that class, that's the strategy pattern, the above is not a strategy pattern, it's a case statement in disguise and it's bad code.

I've seen this pattern in the wild (real world); it works well. Another variant:

  var strategy = {

    ie: function() {this.name="MSIE";},

    ns: function() {this.name="Netscape";}

  };

  strategy.op = function() {this.name="Opera";};

  var obj = new strategy[getClientUserAgentId()]();

  window.alert(obj.name);

-- Jimmy Cerra

12. Other than this, naming standards and other conventions should follow Java programming language conventions. Ahem... <g> I'd propose following as many LispLanguage conventions as possible with JavaScript C-like syntax... or at least giving a good rethinking to this... For example, while running capitals are okay, even WikiWiki uses them!, underscored_names like recommended in PerlLanguage, for example, are more easily readable, and closer to the LispLanguage and SchemeLanguage conventions as well... -- DavidDeLis

13. Document any return values using an @return JavaDoc-style comment. JavaScriptIsNotJava?

These are some suggestions to improve developers' life a bit. Please enhance this list to have better conventions. -- VhIndukumar

It's a good list of recommendations, and the intention and idea are excellent. But I can feel a certain tendency towards Java. While JavaLanguage is a powerul tool, and JavaScript certainly has 'java' in the name, it's not java, just a victim of marketroids. We should try to find more idiomatic recommendations. The differences between both languages deserve some credit, so to say. Just my thoughts, though... I will try to think on more suggestions. Thank you -- DavidDeLis

'' * 12. Other than this, naming standards and other conventions should follow Java programming language conventions. - JavaScriptIsNotJava?

It appears to me that JavaScript is much closer to SmalltalkLanguage than to JavaLanguage or CeeLanguage, specifically with respect to dynamic typing, name scoping, and compilation issues. I therefore suspect that the naming standards and other conventions developed over the 20+ year experience of the Smalltalk community will serve better than the Java conventions. -- TomStambaugh.