Package and Class File Standards

[[email protected]…]

I'm pasting some of the standards I'm abiding by while creating the dojo.presentation framework.

I figured I'd just float them here in case other's wanted to use them as well / peer review.

-------------------------------------------

Dojo Presentation Standards

-------------------------------------------

Activity Diagram / Sequence Diagram Like Descriptions

Use class name dot variable/method when documenting.

Use Class.referenceName when explaining a use of a specific class reference.

Use Class.method(), with the (), so that it's clear that it's a method being explained.

See the dojo.presentation.application.ViewHandler? introduction in the ViewHandler?.js file for an example.

Packages and Classes Only

Follow a Java like packaging scheme.

Put classes in their own class.js file.

That way js files are for classes, and their corresponding directory is a package.

This makes dojo cleaner and easier to document, explain, and understand.

Soap Box: When I started with dojo, it took a nice chunk of time to understand modules, packages, and classes, since the mapping did not directly correspond to java.

Eliminating modules may mean redefining some current packages, since package.subpackage.* would always import all the classes, but that should be a good thing.

More customization beyond this should be supported by Dojo tools, per specific use cases.

Use of double_underline+package+double_underline.js

package.js imports all classes in a package.

No Modules

Make modules non-existant.

Put utility functions in utility classes.

Make utility methods static

[[email protected]…]

Use Labeled Boolean Conditions

create boolean variables like this:

isBooleanCondition = An expression that determines whether the boolean is true for false

isBooleanAnotherCondition = An expression that determines whether the boolean is true or false

Then use the labeled condition inside decision blocks like if blocks.

Example:

isViewRestored = context.application.viewMap.item(toId);

if ( isViewRestored ) {

this.paintTargetView();

}

[Tom Trenka]

This terminology is being debated to death by the committers but there is an emerging standard, information of which is available at dojo.jot.com. The terminology to be used is:

Resource: JS code that is loaded by dojo.require. An example would be dojo.html.common.

Module: A collection of code underneath the same namespace (*not* XML Namespace); for instance, dojo.html is considered to be a module.

Those are the main two. There are no such things as classes in JavaScript? but the term is still being used by some to understand how a constructor works.

A few other things: JavaScript? is *not* Java, and we aren't going to start following a "class per file" methodology--unless it makes sense for the constructor in question to be in it's own resource (for instance, dojo.declare). The reason is twofold: the flexibility of JS makes it very attractive as a way of incrementally adding functionality via mixins, and not everything in Dojo (or JS for that matter) is constructor-based.

If you'd like you can make suggestions for the documentation efforts on the Dojo Interest list.