SYNOPSIS

This document describes the coding style used in Wikiwyg.

This is the first major Javascript project for the current developers of Wikiwyg. It seems worthwhile to write down the coding style decisions. Perhaps someday there will emerge more definitive standards for how to do good javascript.


CLASSES

Yes, in truth, Javascript does not use class based OO. Still it can be useful to think in those terms. Especially for a group of Perl expats. ;)

All classes in Wikiwyg are defined as Subclass objects. The class My.Class which is a subclass of Your.Class is defined like this:

    var proto = new Subclass('My.Class', 'Your.Class');

The Subclass constructor is a simple class generator that generates a constructor for your class, puts it in the symbol table, and gives the prototype a few helpful properties:

classname
The class name of an object. Useful for introspection.

baseclass
The base class name of an object.

superfunc('method_name')
This method allows you to call a particular method, higher in the inheritance hierarchy.
    proto.foo = function(xyz) {
        this.superfunc('foo').call(this, xyz);
    }

The Subclass constructor returns the prototype of the new class, which is handy to use to add more properties to the prototype.


METHODS

Wikiwyg has a few different kinds of methods.

Public instance methods
Most of the methods are instance methods (as opposed to class methods). All this means is that they are functions assigned to the prototype of the class object.
    proto.doSomething = function() { ... };

That the method is Public just means that it is intended to be supported asis in the future. Put another way, public methods form the API of a class.

Private instance methods
Private instance methods differ from publics ones, in that they are not guaranteed to be around in later releases of the code.
    proto.do_something_else = function() { ... };

Public class methods
Some methods are just helper functions and don't have anything to do with an object instance.
    klass.helperFunction(foo) { ... };

For the most part, all class methods are public in Wikiwyg. Also most of them are defined in the 'Wikiwyg' class.


IDENTIFIERS

Wikiwyg uses several styles of identifiers:

Titlecased
A single word with the first letter capitalized. These identifiers are only used for the parts of class names.
    proto = new Subclass('Foo.Bar.Baz');

If multiple words must be specified, use CamelCase.

mountainCasedWords
Multiple words with the first one lower case and the rest title case. Used for public method names. There are some public methods which use lowercase_words, but they are a special case.

lower_case_words_with_underscores
These indentifiers are used for private method names and for variable names.

They are also used for a special kind of public method. Methods that begin with 'do_' or 'format_' are public.

lowercase
Single lowercase words are used for more generic or less important variable names. They are also used for a few very common public properties like config.

i
Single letter identifiers are only used for things like i for a loop iterator.

SEMICOLONS

For the most part, Javascript dows not require semicolons to terminate statements. Nonetheless, Wikiwyg terminates almost all statements with semicolons because they make the code more legible. They convey to the maintainer where the statement is intended to end.

There ar a couple exceptions to the rule though.

    proto.two = function() {
        return 2;
    }

There is no semicolon after the function definition. Even though technically this is the end of an assignment statement, the '}' is sufficient to convey that meaning.

On the other hand:

    proto.two = function() { return 2 };

In the above case, when the function assignment is all on one line, the inner statement should not have a semicolon, but the entire statement should.

BRACES

Javascript allows single statement blocks to be free of braces. Although sometimes this makes code less verbose looking, it has proven a bad idea to do this everywhere that it is allowed. It makes the code more fragile to changing because you have to always be aware when you need the braces. Unfortunately, Javascript will not warn you when you are about to shoot yourself in the foot.

Wikiwyg uses the following guidelines for braces.


OTHER