- The Essence of Fusedoc
- Tools for Fusedoc
- Fusedoc in Applications
Fusedoc in Applications
It's worth mentioning yet again that the purpose of Fusedoc is to communicate information between members of a development team, even if the members are me, myself, and I. We will start with the point at which the architect hands information to a fusecoder in the form of a fusestub.
FuseStubs
A fusestub is the combination of a Fusedoc and any HTML from the prototype that belongs to the fuse. This is the means by which the architect tells the fusecoder about two vital areas: the development environment (in the Fusedoc) and the presentation (in the HTML).
Figure 1 shows a simple fusestub for a login form. The top part of the form shows the Fusedoc, and the bottom has the HTML that was pulled from the prototype.
Figure 1 Fusestub for login form fuse.
The fusecoder's job is to turn the fusestub into a finished fuse by writing any code that is necessary to achieve the objectives described in the "Requirements" section of the Fusedoc. This includes making any outputs from the fuse conform to the Fusedoc.
A common misconception exists about Fusedocs and the information they are intended to convey. Some Fuseboxers are intent on finding ways to communicate presentation information, such as style names, through Fusedocs. Fusedocs are not intended to communicate anything about presentation or visual design. Fusedocs are only intended to contain information about the ColdFusion development environment. They are communication conduits between the application architect and the fusecoder. If you are tempted to include design-related information in a Fusedoc, stop yourself and make a mental note about to whom the Fusedoc is talking.
Design information, on the other hand, must be included in the fuse somehow; otherwise, the fusecoder has no way of knowing what a display fuse is supposed to look like. This is where the world of the designer collides with the world of the developer. To prevent the collision from being catastrophic, we make use of a fusestub.
Fusedocs During Coding
As the coding process continues, the only alterations that should be made to Fusedocs, ideally, are the addition of <history> and <note> elements to help track progress.
Of course, this assumes that the architect is perfect and has missed nothing in the creation of the Fusedocs for the entire system. This is seldom the case. In reality, oversights must be adjusted, and the Fusedoc for a fuse should always reflect the correct state of the fuse. However, this does not mean that team members should run up and change the Fusedoc at every whim. The desire to change a Fusedoc should prompt a discussion between members of the team to determine if the change is appropriate and whether it has a broader implication in the overall project. Fusedoc reinforces Fusebox's overall emphasis on structure and consistency.
Fusedoc for Success
Fusedoc is essentially a meta-language (a language about language) whose subject is fuses. Some programming disciplines introduce the concept of a program definition language, or PDL. These are simply formalized ways to describe programs.
Fusedocs convey all the information that a coder needs to write a fuse, and nothing more. For display fuses, HTML from the prototype is joined with the Fusedoc to provide a fusestub for the coder. The Fusedoc carries the programming environment information, whereas the HTML carries the presentation information.
Fusedoc's two goals are simple: to force the architect to carefully consider the needs of the system, and to provide carefully constructed information to the rest of the team.
In achieving these two objectives, Fusedoc also provides secondary rewards. An application that has effective Fusedocs is inherently well documented. Because the Fusedoc is an integral part of the fuse's code, it travels with the fuse as part of the program code; therefore, it is not necessary to look up entries in an external form of documentation to get at important program information. This also means that, if we construct an application from a collection of fuses that was originally built in other applications, each fuse retains its original documentation; we are not forced to cobble together bits and pieces of documentation from each of the donor systems.
As a documentation system, Fusedoc provides a great deal of power to a development team. By knowing what's going to be written before the coding begins, the team can focus on writing great code instead of solving all the design-related problems while coding is underway.
About this Article
If you would like to read more on Fusedoc, see Chapter 7 in Fusebox: Developing ColdFusion Applications (New Riders, 2002) by Jeffery Peters and Nat Papovich. This book is a comprehensive resource for all your Fusebox needs.