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:
Developing
ColdFusion Applications, about his upcoming presentation at
the
Fusebox 2003 conference (www.cfconf.org/fusebox2003).
FB: Jeff, what are you speaking on at the conference?
JP: Fusedocs.
FB: For someone who doesn't know what Fusedocs are, can you
define
Fusedocs?
JP: Sure, Fusedocs are a standardized way of writing fuse
documentation. They (should) appear at the top of every fuse
in a
Fusebox app.
FB: Ah, documentation is always a PITA, no?
JP: Not with Fusedocs. First, though, you should understand
that
Fusedocs are not so much meant to memorialize code as to provide
a
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
the fact.
That leads to a lot of worthless documentation?stuff that
looks like this:
<!--- loop over products query --->
<cfoutput query="Products">
blah blah blah
</cfoutput>
FB: I see a lot of documentation that looks like that, but
you say it's
useless. Why?
JP: Maybe "useless" isn't the right way to put
it. Maybe "worse than
useless" is more accurate. That comment doesn't provide
any
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
than
useless.
FB: And Fusedoc is different?
JP: Very different. Instead of having inline comments, the
architect
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
example I
gave, the "documentation" was written after the
fact. In the case of
Fusedocs, the documentation is written first and forms a sort
of work
order for the coder.
FB: That sounds pretty interesting. So what would the Fusedoc
look like?
JP: It might look something like this:
<fusedoc
fuse="dspProductsList.cfm"
language="ColdFusion"
version="2.0">
<responsibilities>
I
display a list of products with links to buy each product.
</responsibilities>
<properties>
<history
author="Jeff Peters" email="[email protected]"
/>
</properties>
<io>
<in>
<string
name="self" />
<query
name="products">
<string
name="productID" />
<string
name="description" />
<number
name="price" precision="decimal" />
<string
name="image" />
</query>
<string
name="XFA.buyProduct" />
</in>
<out>
<string
name="fuseaction" scope="formorurl" />
<string
name="productID" condition="on XFA.buyProduct"
/>
</out>
</io>
</fusedoc>
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
get this
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
receive a
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
are available
and what ones I should?and should NOT?set, yes. And you said
the
architect writes this?
JP: Yes, a typical Fusebox project can be broken into pieces
that can
be handled by different people. The most critical person is
the architect.
It's their job to make sure that all the little pieces work
together to
produce the application. And that means that it is NOT the
coder's
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
family
and their behavior in the great outdoors.
FB: OK, but what about all that code? And all XML? Do all
architects
have to become fluent in XML?
JP: Not really. They just have to learn the available Fusedoc
tags. And
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
at
halhelms.com. That's strictly optional, for those of us who
like seeing
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
how to
document an application. It's documented before the first
line of code is
written!
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
boss tells
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
building
something simple?maybe all the forms for an application.
FB: That would be fantastic. Are there any other tools for
this?
JP: Sure! I built some pretty neat tools for working with
Fusedocs at
grokfusebox.com and I'll be talking about a new generation
of Fusedoc
tools at the conference.
FB: Thanks, Jeff. I'll be there to hear the latest.
Previous weeks:
Week 1: Ben Edwards
Week 2: Michael Smith
Week 3:
John Quarto-von Tivadar
Week 4:
Hal Helms
