Opened 14 years ago
Closed 14 years ago
#1448 closed enhancement (invalid)
Package and Class File Standards
Reported by: | Owned by: | anonymous | |
---|---|---|---|
Priority: | high | Milestone: | 0.9 |
Component: | General | Version: | 0.3 |
Keywords: | Cc: | ||
Blocked By: | Blocking: |
Description
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
Change History (3)
comment:1 Changed 14 years ago by
comment:2 Changed 14 years ago by
Milestone: | → 0.5 |
---|---|
Version: | 0.2 → 0.3 |
comment:3 Changed 14 years ago by
Resolution: | → invalid |
---|---|
Status: | new → closed |
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.
Use Labeled Boolean Conditions