The original "The Dojo Way" article can be found here.

This page is here just so that people can get their thoughts and philosphies down. There will be no voting, this page might not even be used at all. The plan is simply to let this page influence how and if we edit "The Dojo Way" in its upcoming revisions.

The structure is in statement/reaction format. The goal is to cover all the different areas that might shed light on our project philosophy. These include both positive and negative things. We might be doing things that diverge from the statement of the original Dojo Way that might be bad for the project, and some that are good for the project. On the other hand, we might feel more strongly about certain topics than we did before.

Try to react to the article, not the feelings of other people. The goal is not to change someone else's opinion, but to know what their opinion is. But if the opinion of someone else reminds you of something, go ahead and add it.

Understanding Your Own Footprint

Every useful system carries the imprint of its designers. From bridges to spoons, the expression of a builder's skill, philosophies, and production constraints are exposed in the final product. Software is no different, except in its propensity to change. Software mutates in response to users needs, and in that change, a continual re-impriting of a designer's skill and sense of taste takes place.

This has the potential to cause continuity problems for others, be they end users or other developers. Reducing these confusing aspects (cognitive load) allows software consumers of every type to feel better about a block of code. With every interaction, their pre-conceived notions of how the thing will behave serve them instead of forming an obstacle for them to overcome. Their instincts are turned into a valuable tool by elegantly and consistently designed software.

Dojo, as a project, should meet expectations in this way. This doesn't mean that you have to agree with every design decision that's been made in the project (dissent is healthy) or that the guiding principles outlined here are written in stone. They should, however, capture the way design choices have been made to date and serve as a guide for making future decisions.

Commentary (trt, 10/19):
The breadth of the experience of the committer base would be best served by developing some sort of (dare I say it) mission statements, with both new and existing parts of the codebase.  It's not such a big deal with fairly isolated code (gfx, lfx, collections and crypto fall into this category) but for something like the widget system and even dojo.data, it would be a good idea to have some sort of guiding statement.  There are simply too many different experience points and approaches that are pulling portions of the code in more than one direction, without any kind of person serving a gatekeeper function.  The glaring example would be the widget system; some sort of mission statement (such as the Dojo Way statement) would probably go a long ways towards refining the development approach there.

Refactoring Efforts

A lot of our code has gone through fairly large refactoring. In a lot of ways, this fits with the ideas presented above. We should be engineering a better product. What we need to settle on is what types of refactoring we should be involved with. Does the refactoring make a better product? Did we do this based on users' needs, or because it seemed like a good thing to do? Have we made sure we aren't doing something that's already been done and failed? Do we even have a way to check what's been attempted before?

Commentary (trt, 10/19):
Speaking only to the HTML refactor efforts, we undertook that for two reasons: efficiency and codebase reduction, both of which were common complaints.  We also attempted to use that particular effort as a demonstration of what we believed to be a standardized "Dojo way" approach, in terms of how the code should operate--more reliance on objects as return arguments, and more reliance on keyword objects as arguments, as a way of stabilizing an API signature without destroying the need to be flexible.

The Design Process

Should we create a general set of rules as to what needs to be done when building a system or refactoring? We need to make sure that the community knows why we're doing something, how we're going to do it, and how they can be involved. It will also serve as a firm resource to point someone to when they question why something was designed the way it was.

Commentary (trt, 10/19):
Like I mentioned above with "mission statements", I do believe that we should come up with some sort of guide for design and architecture; it will help quite a bit in terms of "presenting a united front", if you will.

(pottedmeat)
It seems to make sense to provide the community with the philosophies behind any change. This applies to both refactoring and design. It would seem like part of "The Dojo Way" should be transparency of development. If someone has an agenda, or a perspective from which they approach something, we all should know. Otherwise, we might end up in a situation where a design or refactoring effort has a clear skew to it which no one wants to admit, which we can't disagree with because it's not on the table to discuss to begin with. Transparency fosters helpful disagreement.

Deprecation

We need to make sure that we have clear guidelines for how deprecation should happen, and how long it should be left deprecated. Ideally, no user should have broken code when they update, just lots of deprecation messages.

(pottedmeat)
I agree with the quote "With every interaction, their pre-conceived notions of how the thing will behave serve them instead of forming an obstacle for them to overcome". I think the expected behaviour of deprecation is that if they consistently update their code, it will not break, and it will kindly alert them to the path to take to get their code in sync. This will also encourage more frequent updates of their code base.

Dojo Guiding Principles

Reduce barriers to adoption.

Simply put, do not give users reasons not to choose your code. This affects everything from design to licensing to packaging.

Simple first, fast later

Make it simple to use first, make it fast when it's approprite. Simple here means simple for users, not for us. We should work as hard as necessary to make things simple for end users. This principle goes to reducing barriers to adoption. Things should be as easy as possible for the common case but transparently "upgradeable" to a faster code path if the end user is willing to learn about the performance dials and knobs.

Bend to the constraints of your environment

Do not bludgeon a problem to death with code. If the environment can do most of something, let it. Fill in as necessary, but do not re-invent. Make the path smooth for users, but do not introduce your own idioms where they aren't required.

Commentary (trt, 10/19):
Privately I have brought up the idea of splitting parts of the Dojo codebase out of what most would consider "the core" and into sub-projects.  My concern is that the perception of Dojo overall (as pointed out sarcastically by the jQuery crowd with the elephant representation) is that we have a huge library of code.  One of the main reasons for the success of Prototype isn't that it's lightweight but that it's perceived to be lightweight--because it was designed to act as a core on top of which other things can be built.

In addition, I think our prevailing attitude in terms of code contribution right now (by this, I'm referring to the tendency to ask someone to sign a CLA and make thier code part of Dojo) is the wrong approach.  We should be encouraging people to develop code that sits on top of various parts of Dojo without forcing anyone to contribute that package to Dojo itself, or sign (what some think is) a prohibitive contributor agreement.  In short, we should be encouraging things like Rico and Scriptaculous being built on top of a Dojo core.

Over-engineering

We want Dojo to appeal to as many types of users as possible. Our current attitude seems to be "write once, run everywhere", while for some users, this is like using a hammer to kill a fly. We need to think about isolating our complex code from our simple code. JavaScript has amazing capabilities in this area, including the wonderful mixin.

(pottedmeat)
There should be a limit to how big a simple test case should be. A "Hello World" widget is absolute huge. WIth any module, even something like dojo.uuid, we should be aware of the size hit for what is potentially a very simple operation.

Simplicity

This ties into the "Over-engineering" heading. If we have an API and a toolset that goes way beyond the needs of the user, the simplicity is lost.

Straying from our JavaScript roots

Since this was written, we've introduced a heavyweight widget system, dojo.declare, dojo.widget.defineWidget, and many other tools that look less and less like HTML and JavaScript. Is this where the community wants to go? Are we worried about looking like MochiKit or Prototype.

(pottedmeat)
We need to be concious of each other's understanding of JavaScript. We should be giving deserved respect to those who "get" JavaScript more than us, no matter how much we ourselves feel we understand it. At the same time, all the fascilities should be in place to aide each other on in our learning and understanding. This, I feel, should be part of our overall philosophy, that we want our developers to be as educated as possible and will provide them with the tools they need.

Other Points

Interdependency

Dojo was originally introduced as a system of modular components. Grouping them in the same repository was intended to be for ease of use, not so that they would all depend on each other. We need to define clear guidelines as to what modules should work together and which should not.

(pottedmeat)
I think it was/should be part of our core philosophy to stay away from interdependant code. Part of why a build that only has a small piece of functionality can be so huge is not because one file requires another file, but that other file requires another file, which requires two files, etc...  I need to shortly draw out a dependency chain so that this will become more clear. We need to start thinking of modules as apart from each other. Having them all in our repository is confusing sometimes because they seem to be a cohesive whole. Dojo is called a "toolkit" and I view each module as a tool, or a building block. Our philosophy should be in providing the building blocks, not the whole house.

Playing to JavaScript's strengths

JavaScript is a powerful language, if used the right way. There are many problems we encounter that might be solved by playing to the strengths of the language rather than coming up with our own solution. The mutability and dynamic nature of JavaScript should be utilized before crafting more complicated solutions.

Protecting Developers

Should we add in a lot of extra code for fringe cases where the developer might screw up?

(pottedmeat)
Null checking is a good thing, enabling developers to be lazy is a bad thing. There has to be a balance of supporting "pre-conceived notions of how the thing will behave serve them instead of forming an obstacle for them to overcome" without handing it to them on a silver platter. Part of what makes good code great is by having a base on which to build on that doesn't pretend to know what your code problems are. We need a mutable base if you will, which is one of the strengths of JavaScript anyway.

Commentary (trt, 10/19):
One of the biggest issues I have with some of the Dojo code is the way that many errors are trapped, particularly with the widget system.  More transparency (and better error messages) are a way of handling this, but more importantly if that trapping is there to supress errors that are being thrown all the time, then we've done something wrong.

Documentation

Is good documentation now a central project philosophy?

Commentary (trt, 10/19):
Good documentation should always be a central project philosophy; I think the real question here is how much of that should be baked into the code itself.  This was a long and arduous argument among committers when Neil first started working on the doc parser project; since then, many new people from different backgrounds (notably the IBM, AOL and Sun groups) have joined the committer pool, and (consequently) have thier own ideas about docs.

One thing I would like to remind all of (pointing at the JavaDoc? approach) is that not everyone uses an IDE to develop code, and therefore large comment blocks can interfere with code comprehension and coherence.  Our philosophy here should be that the source code should be able to speak for itself, as much as possible--with particularly tricky concepts being explained in one place, as opposed to being sprinkled throughout a file.