Each week from now until the Fusebox conference (Aug
31 - Sep 1), we're talking with one of the conference speakers.
WEEK 5: Jeff Peters
This week, we're talking with Jeff Peters, author of Fusebox:
ColdFusion Applications, about his upcoming presentation at
Fusebox 2003 conference (www.cfconf.org/fusebox2003).
FB: Jeff, what are you speaking on at the conference?
FB: For someone who doesn't know what Fusedocs are, can you
JP: Sure, Fusedocs are a standardized way of writing fuse
documentation. They (should) appear at the top of every fuse
FB: Ah, documentation is always a PITA, no?
JP: Not with Fusedocs. First, though, you should understand
Fusedocs are not so much meant to memorialize code as to provide
specification for that code.
FB: Hmmm...that sounds deep. What's it mean?
JP: Most documentation is written?if it's written at all!?after
That leads to a lot of worthless documentation?stuff that
looks like this:
<!--- loop over products query --->
blah blah blah
FB: I see a lot of documentation that looks like that, but
you say it's
JP: Maybe "useless" isn't the right way to put
it. Maybe "worse than
useless" is more accurate. That comment doesn't provide
information that a cursory glance at the code would give.
That makes it
useless. The fact that it takes a coder's time makes it worse
FB: And Fusedoc is different?
JP: Very different. Instead of having inline comments, the
provides a Fusedoc that tells the fuse coder everything he
or she needs
to know to write the fuse. You see the difference? In the
gave, the "documentation" was written after the
fact. In the case of
Fusedocs, the documentation is written first and forms a sort
order for the coder.
FB: That sounds pretty interesting. So what would the Fusedoc
JP: It might look something like this:
display a list of products with links to buy each product.
author="Jeff Peters" email="email@example.com"
name="price" precision="decimal" />
name="fuseaction" scope="formorurl" />
name="productID" condition="on XFA.buyProduct"
FB: Wow, that's a lot of info?and it's all in XML.
JP: Yes, but imagine that you are the fuse coder and you
Fusedoc atop a prototype page that lists all the products
for sale. What
would the Fusedoc tell you? It says that the purpose of the
fuse is to
list products and link them for a sale. It says who wrote
the fuse and
how to contact them. It says that you, the fuse coder, will
string named "self", a query named "products"
(with four columns), and
an XFA named "buyProduct". And it says you should
send out of the
fuse a variable called "fuseaction" and?in the case
where the XFA is
buyProduct?you should send out a "productID". That's
really all you
need to know. Wouldn't that be nice to have?
FB: It's a lot better than trying to guess what variables
and what ones I should?and should NOT?set, yes. And you said
architect writes this?
JP: Yes, a typical Fusebox project can be broken into pieces
be handled by different people. The most critical person is
It's their job to make sure that all the little pieces work
produce the application. And that means that it is NOT the
responsibility: they just have to follow the Fusedoc.
FB: Well, does it work?
JP: I'm tempted to ask a question about members of the Ursus
and their behavior in the great outdoors.
FB: OK, but what about all that code? And all XML? Do all
have to become fluent in XML?
JP: Not really. They just have to learn the available Fusedoc
the good news is that there are tag extensions for Dreamweaver,
Homesite, and Studio that make that a snap.
FB: How do you know when to use which Fusedoc elements?
JP: Well, I'll be talking about that, but there's a DTD available
halhelms.com. That's strictly optional, for those of us who
things like DTDs. It's really pretty easy to learn and to
use. And the
benefits are enormous.
FB: What sort of benefits?
JP: Well, for one thing, it solves a major problem of deciding
document an application. It's documented before the first
line of code is
FB: That is big.
JP: Huge. Another benefit is that it lets an application
be broken into
many small pieces that coders of very different skill levels
can work on.
You know the problem where you're working on a job and the
you that an intern can "help" you?
FB: Yes. That's worse than no help at all.
JP: But if you had Fusedocs, you could set the intern to
something simple?maybe all the forms for an application.
FB: That would be fantastic. Are there any other tools for
JP: Sure! I built some pretty neat tools for working with
grokfusebox.com and I'll be talking about a new generation
tools at the conference.
FB: Thanks, Jeff. I'll be there to hear the latest.
Week 1: Ben Edwards
Week 2: Michael Smith
John Quarto-von Tivadar