> After running my site with a partial fusebox implementation for several
months I have decided to rebuild it "correctly". I am writing the fusedocs
for my files and have a question: when youlist persistent variables in the
doc, do you list every one that is available or do you just list the ones
that are relevant to the specific fuse?
>
> I am curious because it might make future modifications easier for a
newcomer if you list all persistent variables. However, this list could get
pretty huge for every fuse. Thoughts?
>
if the architect has properly written the fusedoc which includes only what
the fuse is intended to do and the variables needed then to do that, then
that is all that fuse ever cares about. In fact this is the heart of the
matter since you mention above "persistent variables"--in fact persistent
variables are the *only* variables that should be in the fusedoc because all
non-persistant onces (ie local variables whose scope is VARIABLES) are
useless in the context of the fusedoc---the purpose of the fusedoc is to
describe what the code following is to do, and to describe variables going
in to accomplish same or variables going out as a result of same. The
fusedoc is not to explain the "how" of writing the code and all local
variables are "how" variables.
In terms of what you're describing let me make a small analogy why it is not
a good idea: I think the idea of listing all persistent variables in a
fusedoc, whether used by the fuse or not, is absolutely analogous with a
non-normalized database--absolutely you can have a DB that works when it is
non-normalized (in fact the problem with learning to normalize is that
breaking the rule doesn't early on result in a bad result from the DB--it is
the cumulative long-term maintenance and growth issues that eventually slap
you on the wrist!). But when a new persistant variable is added to the
application, then you are going to have to update ALL the fusedocs in every
fusebox file. Ugh. Even worse if you modify only the description of said
variable. Ugh, Ugh, Ugh.
So let's not mix apples and oranges, here the apple being documenting a
Fuse's modular functionality and the orange being documenting an
application's variables list.
Here are several suggestions for accomplishing what you want.
1) write a "fusedoc" for your index.cfm. Since everything passes through
it, it is appropriate here to list all persistent variables here. So now
you're being consistent with the Fusedoc ideology. However to keep the
index.cfm simple-reading, don't write it there in the index.cfm (or even
<CFINCLUDE> it in the index.cfm)---just write a separate file, existing in
the app's root perhaps near the configuration file(s) that documents all the
persistant variables.
2) use Lee's Fusedoc Browser (see other references on this list for the most
recent copy) to get a list of all fusedocs across all files in an app. If
you follow (1) above then the fusedoc browser will work on it, too.
as a final note, another philosophical reason for the fusedoc
documentationology (is that a word? Certainly Hal deserves his own words) is
that the person writing the fuse doesn't need to know anything about
anything other than that fuse. This doesn't mean that they *shouldn't* know
anything about other parts of the app -- just that the goal is to reduce the
burden on the app's architect so that he can distribute the load of coding
to less-senior (cheaper and more plentiful) developers--and thereby to break
a large project into successively smaller pieces, each of which is more
easily conquered. If you were to have included all the persistent variables
in every fusedoc then you're giving people WAY more info than they require
to accomplish the tag.
I'm reminded of the adage of the three states of knowledge experience:
1) people who don't know, and don't know that they don't know
2) people who don't know , but think they know
3) people who know, and know that they know
the only dangerous people are in group (2)--mostly, they are dangerous to
themselves. What the Fusebox methodology does is break the application into
smaller pieces, and what the Fusedoc documentationology does by telling them
only what is required is convert people from (1) to (3), just on a smaller
knowledge scale, without the intermediary danger step at (2).
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Structure your ColdFusion code with Fusebox. Get the official book at
http://www.fusionauthority.com/bkinfo.cfm
Archives: http://www.mail-archive.com/[email protected]/
Unsubscribe: http://www.houseoffusion.com/index.cfm?sidebar=lists
