Fusedoc
One of the really helpful things about Fusebox is that it makes development by different developers in different locales easy. Since the action flows from fusebox to fuse to fusebox again, there is none of the dependencies between modules that makes distributed development difficult in many other languages.

Without this independence between modules, making almost any change — or adding - to an application requires someone with an encyclopedic knowledge of the entire application. After all, if you don't know what other places a change might affect, only someone very foolhardy is going to plunge ahead.

This often leads to tying up the most experienced developers with everything but the simplest code. The deeper into the project we get, the less the less experienced coders in the team can help. This is sometimes thought of this as an inverted pyramid, where, as the project builds, the entire weight and pressure of an application gets concentrated on fewer and fewer people.

In Fusebox, we have the ability to break up the application into many different pieces. Such "severability" benefits everyone. The customer gets the job sooner and with less stress-induced bugs. The development company lowers the cost of development by spreading the work over more (and usually less expensive) developers. The more experienced developers get to work in areas where their experience and expertise are more critical. This is usually much more satisfying work and they can demand higher pay. Finally, new developers get the valuable experience of working on code throughout an entire application's lifecycle.

In order to gain the full benefits of severability, we need a way of communicating to the fuse coder just the knowledge s/he needs to know to do the job. Fusedoc is a method for writing documentation that succinctly states what a coder needs to know to write a fuse. With the advent of version 3.0 of Fusebox, Fusedoc has gone to an XML-based format.

A Fusedoc is set as a comment at the top of a fuse file. Here's one for a login form:

<!---
<fusedoc fuse="dspLogin.cfm">
   <responsibilities>
      I provide a login form for users.
   </responsibilities>
   <properties>
      <history
         author="Hal Helms"
         date="10.4.2001"
         email="hal.helms@teammacromedia.com"
         type="create"/>
   </properties>
   <io>
      <in>
         <string name="self" scope="variables"/>
         <string name="XFA.onSubmitForm"/>
      </in>
      <out>
         <string name="userName" scope="FormOrURL"/>
         <password name="password" scope="form"/>
         <string name="fuseaction" scope="FormOrURL"/>
      </out>
   </io>
</fusedoc>
--->

Fusedoc starts out with a simple <fusedoc> tag set:

<fusedoc>
</fusedoc>

Inside that are three separate sections: responsibilities, properties and input/output variables, or io, for short.

<fusedoc>
   <responsibilities>
   </responsibilities>

   <properties>
   </properties>

   <io>
   </io>
</fusedoc>

Of these three sub-sections, the only required one is responsibilities.

Responsibilities: Written in the first person, responsibilities tell the programmer exactly what the fuse's job is. Without repeating the information conveyed in the io section, responsibilities should make clear to the coder what the fuse's job is. Some people write these in the first person, finding that putting themselves in the place of the fuse helps better catch the details involved.

Properties: This section has three possible sub-sections: history, property, and note. You can see the history tag in the code for dsp_Login.cfm.

<history
   author="Hal Helms"
   date="10.4.2001"
   email="hal.helms@teammacromedia.com"
   type="create"/>

IO: This section tells us what sort of inputs the fuse can expect and what outputs it's responsible for. Look at the io section of the Fusedoc for dsp_Login.cfm.

<io>
   <in>
      <string name="self" scope="variables"/>
      <string name="XFA.onSubmitForm"/>
      </in>
      <out>
         <string name="userName" scope="FormOrURL"/>
         <password name="password" scope="form"/>
         <string name="fuseaction" scope="FormOrURL"/>
      </out>
</io>

<io></io> is a container. It can contain three different sub-elements: <in></in>, <out></out>, and <passthrough></passthrough>.

The in and out elements are simple enough: they indicate variables that are either being made available to the fuse (in) or that the fuse is responsible for creating (out). In the case of passthrough variables, these are variables that both come in and go out, and are not to change value.

In order to make the adoption of XML Fusedocs easier, both Document Type Definition (DTD) and custom Studio tag editors for the XML-style Fusedoc are available at http://www.fusebox.org

On August 27-31, 2001, Steve Nelson and Hal Helms team up for a "Fusebox 3.0 Architecture" class. This class is meant for people who architect Fusebox applications. Mastering Fusedocs is key to designing Fusebox applications - applications that can be written by a team of programmers who know nothing of the application itself.

Does this work? Take a look at http://www.solutionssite.com. This application was prototyped by a client in Boston, architected in Florida, and sent overseas for coding. If you'd like to learn more - if mastery of Fusebox architecting is your goal - then we invite you to join Steve and Hal for five intense days of Fusebox Architecture training. You'll learn the techniques and tools for designing robust, maintainable, and scalable Fusebox applications. For more information or to sign up, go to http://www.halhelms.com

Written by Hal Helms and Steve Nelson